Replies: 9 comments 28 replies
-
Спасибо! 🚀 🚀 🚀@illright Таки дошли руки до твоего фидбека
ПроблематикаВся кортима и комьюнити сходится во мнении - что документация сильно устарела от текущей версии методологии и требует актуализации Поэтому для нас это сильно зудящая тема, наравне с проработкой концепций
А что-то делается?Начиная с осени мы сильно пересмотрели работу над документацией и дальнейшие приоритеты при ее проработке Пока что кортима сконцентрирована на проработке общей навигации и структуры, но есть и другие направления
Как посодействовать?
|
Beta Was this translation helpful? Give feedback.
-
|
Позже еще отдельно продублируем это все в контрибьюшн-странице |
Beta Was this translation helpful? Give feedback.
-
|
Ну и да - на будущее лучше разбивать каждый такой самостоятельный блок на отдельный тред - чтобы было проще вчитываться, отвечать и обсуждать (во многом и объем цельного текста заставлял переносить задачу изо дня в день) |
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
|
В целом описал по основным моментам @illright если будет еще где дополнить - пиши, оч поможешь
@feature-sliced/core мб вам тоже будет что добавить 🤔 |
Beta Was this translation helpful? Give feedback.
-
RE: Чего хотим достичь
Тут важно добавить - "для новичков в FSD" Писали об этом в "миссии" - "Не выйдет: очень просто, очень понятно, для всех"
Именно для этого в конце и есть навигационные карточки, с контекстом для решения конкретной задачи пользователя 🤔 Аналогично тем, что встречаются в других документациях
По этому - однозначно "да", и этот раздел также:
Для этого даже есть такой набросок из ресерча по реворку: |
Beta Was this translation helpful? Give feedback.
-
|
Да, навигационные карточки – безусловно, хорошо, но сейчас они направляют в разделы, которые сами по себе не очень хорошо отделены от остальных и распределены по обязанностям. Короче говоря, эти карточки не будут работать до тех пор, пока не починим структуру доки. Но идея хорошая, и выглядит красиво |
Beta Was this translation helpful? Give feedback.
-
|
Потому что реструктуризация в процессе, да) Нав.карточки будут работать куда лучше офк, когда реструктуризация закончится, но и одно их наличие это уже гораздо лучше - чем их отсутствие в итак недоструктурированной доке 🤷♂️ Живем компромиссными итерациями |
Beta Was this translation helpful? Give feedback.
-
|
Потому что реструктуризация в процессе, да) Нав.карточки будут работать куда лучше офк, когда реструктуризация закончится, но и одно их наличие это уже гораздо лучше - чем их отсутствие в итак недоструктурированной доке 🤷♂️ Живем компромиссными итерациями |
Beta Was this translation helpful? Give feedback.
-
RE: Проблемы с текущим вариантом
Это как раз то, что мы стали часто слышать ближе к осени - и поэтому сконцентрировались именно на этом Т.к. даже при грамотно написанном материале, но откровенной плохой структуре и навигации - читатель доки не сможет решить свою проблему А значит и ценность такой доки резко сводится к нулю |
Beta Was this translation helpful? Give feedback.
-
|
По каждому пункту отдельно отпишу дальше) |
Beta Was this translation helpful? Give feedback.
-
|
@illright Интересно твое мнение - думаешь было бы лучше, если бы вместо "слоистого торта" в Intro было это?
Или сама структура предполагаемая?
|
Beta Was this translation helpful? Give feedback.
-
|
Не, мне кажется, оба этих варианта – перебор. Вариант с гитхабом сложен тем, что очень много информации размещено на маленькой картинке + непонятны переходы между слоями. То есть, разобрав иллюстрацию для, например, слоя Shared, непонятно по картинке, что меняется при переходе на слой Entities. Потенциальное решение: нарисовать интерактивную диаграмму с анимациями. Это то, о чем я однажды говорил, но в этом дискашне не упоминал. Подробнее отпишу в ишью, направленную на улучшение диаграммы (#178). Вариант с кодом сложен тем, что он довольно сильно оторван от реальности в том плане, что структура папок не помогает понять, как по этим папкам разложить какое-то новое приложение. Эти названия объектов, написанные в комментах, довольно абстракные, тут можно по-разному это понять. Из-за этого мне кажется, что диаграмма структуры файлов будет больше полезна в качестве справочника для тех людей, которые уже познакомились с методологией на базовом уровне, и хотят быстренько вспомнить. |
Beta Was this translation helpful? Give feedback.
-
|
Тип такой анимашки? 🤔 atomic.design.mp4 |
Beta Was this translation helpful? Give feedback.
-
|
Да, в целом, неплохо, но интерактивно (это важно, чтоб она не просто сама постоянно мерцала, а давала возможность читателям разобраться, что именно меняется). Я себе представлял это немного не так – мокап сайта, а справа столбик слоев. Наводишь мышку (клавиатуру) на слой, и на мокапе появляется цветной оверлей, показывающий, какие именно детали сайта затронуты. Возможно, зум картинки для нижних слоев. |
Beta Was this translation helpful? Give feedback.
-
RE: Проблема 1. Много ссылокTLDR
В целом тоже понимаем, и это как раз к тому - чтобы по возможности обойтись без ссылок, где это не нужно (особенно в Intro) И попытаться решить те же проблемы другими способами - чтобы обилие ссылок не сбивало читателя
Как раз то, чем мы хотим заняться после базовой реструктуризации - начать редактировать само содержание каждой конкретной статьи |
Beta Was this translation helpful? Give feedback.
-
Details
Тут я бы уже не сказал, что все так однозначно 🤔
Далеко за примерами ходить не надо Хоть и понятно, что обилие ссылок - может привести вплоть к обратному эффекту, о котором дальше
А сам контекст, помечается отдельными информационными плашками, типа "понятие модуля тут и далее имеет следующее значение..." - нет? 🤔
Мы вообще подумывали о том, чтобы перед каждой статьей в доке - таким образом отдельно прописывать - с чем стоит ознакомиться для понимания, если еще не |
Beta Was this translation helpful? Give feedback.
-
Идея хорошая, надо только реализовать аккуратно, чтоб действительно помогало. Если есть какой-то стайлгайд, как писать страницы документации, это стоит в него добавить, как мне кажется |
Beta Was this translation helpful? Give feedback.
-
RE: Проблема 2. Технический жаргонTLDR
Оно сейчас так и есть, но я согласен - что возможно этот параграф стоит ближе к концу страницы перенести
Тут уже писал выше - но постараемся снизить нагрузку
Тоже писал - быстро это увы не делается, хотя и мы работаем над решениями, которые могли бы ускорить фидбек @illright Но если попадаются при прочтении конкретные зудящие примеры - feel free завести под это ишьюс
Возможно имеет смысл, но опять же - мы не можем, увы, пересказать весь Computer Science и другие подходы в проектировании вместо самих этих подходов
Тут тоже однозначно да, но об этом еще в следующих тредах |
Beta Was this translation helpful? Give feedback.
-
Details
Тут то, что писал чуть выше: "У всех свой уровень опыта проектирования и разработки систем, поэтому стоит понимать следующее: Т.к. ключевая задача документации (по крайней мере, сейчас) - помочь разработчикам решать регулярные проблемы при проектировании Там где можем - добавим контекста для возможных новичков в проектировании, но и объяснять Computer Science во всей доке параллельно основным концепциям FSD - тоже не вариант 🤷♂️
Перечисление принципов нужно как раз, для "весомости" методологии, а также для доп. подкрепления мысли, что методология не содержит сама по себе - ничего нового. Это лишь агрегированный и проработанный набор существующих практик (которые объяснять в доке - кажется тоже расточительно, по отношению к вниманию читателя - см. пункт выше) Хотя согласен, что имеет смысл переформулировать так - чтобы эта мысль читалась получше, и не сбивала внимания читателя
Возможно лучше ссылаться на ВИКИ или более статичные источники Но идея тут ключевая, опять же - не объяснять самим то, что уже хорошо объяснено в других источниках и что мало относится к самой методологии |
Beta Was this translation helpful? Give feedback.
-
Не сильно отличается от "Она нацелена на разделение приложения согласно бизнес-логике и областям ответственности.", но звучит получше - согласен 👍
Согласен, дока по масштабам большая и не все, увы, удалось довести до "эталонного" состояния @illright Если найдутся еще примеры таких англицизмов - дай знать |
Beta Was this translation helpful? Give feedback.
-
Безусловно. Однако, лично для меня термин "бизнес-юниты", в отличие от, например, "SOLID", не звучит как что-то, что введено в обиход в конкретном месте. Скорее, это звучит как баззворд, который все употребляют так, как им вздумается. Поэтому, когда я вижу в доке термин "бизнес-юниты", я чувствую потерянность, и при этом не считаю гугление этого термина перспективным, так что просто ною и игнорирую непонятный мне термин.
Понимаю, но это не помогает войти в методологию лично мне. Это звучит как попытка оправдаться перед критиками, но по странице Введение, вроде бы, странно критиковать. Мой поинт в том, что любая аргументация дизайн-решений и установка "весомости" методологии заслуживают отдельный раздел, который и стоит читать людям, скептичным насчёт этой методологии. Для всех остальных эта информация только создаёт больше вопросов, которых поначалу и так немало. Кхм, имхо. |
Beta Was this translation helpful? Give feedback.
-
RE: Проблема 3. Смысловое пересечение с другими страницами.TLDR
Тут да надо еще раз зафиксировать, чего не хватает, а что стоит даже убрать
Да, думаю суть в переименовании именно
Прорабатываем) @illright Но если есть свое видение, какие должны быть раздели - feel free поделиться
Тут тоже интересный пункт) Если вкратце - то теги эти нужны во многом, чтобы пользователь сам понимал, что ему ждать в этом разделе (как в том же гэтсби) Для этого же нужны и краткие описания для каждого раздела - чтобы пользователь не распылял свое внимание зазря @illright Но ты говоришь, что тебе это скорее мешает... А каким бы ты хотел видеть подсказки по навигации по конкретным разделам? 🤔 |
Beta Was this translation helpful? Give feedback.
-
|
Вот тут позвольте не согласиться. На мой взгляд, ни русский вариант "Быстрый старт", ни английский "Get Started" не решает проблему пересечения с Введением. Сейчас постараюсь пояснить. На мой взгляд, флоу по документации должна быть примерно следующий: (1) Введение – обязательно для чтения всем, так что максимально по делу и без сложностей, а также без оправданий. Это не полноценный флоу, здесь опущены некоторые важные страницы типа Аргументации, Журнала Изменений и прочего. Таким образом, я не очень релейчу к идее разделять на Beginner-Elementary-Intermediate-Advanced – попросту не вижу в этом смысла и пользы для конечного пользователя. Есть что-то, что обязательно читать, есть что-то, что можно сделать как вздумается, но можно и прочитать, как люди до этого делали. В особенности я не релейчу к представленному делению. Что Введение – это для Beginner, Быстрый Старт – это для Elementary, и т.д. Создаётся впечатление, что Быстрый Старт говорит то же, что и Введение, только в больших подробностях, что не очень с точки зрения разделения обязанностей. |
Beta Was this translation helpful? Give feedback.
-
|
А теперь про теги.
В доке Гэтсби некоторые вещи сделаны лучше, чем во FSD, из-за чего некоторые вещи, которые работают для Гэтсби, перестают работать здесь. В частности я, конечно, говорю о структуре документации. Честно говоря, на мой взгляд, нужно сделать так, чтоб теги банально не были нужны. Чтоб у доки был четкий, максимально линейный флоу, а все страницы-ответвления своим названием и первым абзацем давали понять, стоит ли это читать. Ну и конечно, минимизировать количество страниц в целом, это всегда хорошо, когда делается без ущерба для информативности. |
Beta Was this translation helpful? Give feedback.
-
Ну да, тут не в чистом виде beginner-elementary-..., но при этом каждый следующий раздел - должен расширять понимание предыдущего
Плюс мы стараемся не сильно отходить от diataxis в данном вопросе: |
Beta Was this translation helpful? Give feedback.
-
|
Но за мнение спасибо, постараемся учесть при дальнейшей реструктуризации 🤔 |
Beta Was this translation helpful? Give feedback.
-
Да, безусловно Если так воспринимать - то на текущей итерации теги это скорее временно-постоянный костыль для хотя бы базового упрощения навигации (тем, кто сможет обратить на это внимание) И безусловно - "лучше чтоб было проработанно полностью, а не частями и большими мазками" Это как раз то, над чем щас активно работаем) |
Beta Was this translation helpful? Give feedback.
-
RE: Проблема 4. Отсутствие введения как таковогоTLDR
Тут скорее соглашусь - возможно такое лучше будет перенести в GetStarted А в введении оставить больше общей overview-инфы
Те же самые планы и у кортимы) |
Beta Was this translation helpful? Give feedback.
-
Details
Хотелось как-то выделить отдельно, но опять же - щас действительно выглядит "слишком fancy"
Это скорее предупреждение для всей доки, чтобы людей не путали примеры чисто на реакте, чтоб не писать в каждой конкретной странице
Не уверен, что до конца твою мысль тот уловил - но в целом соглы 🤔
Пробовал по-разному, когда реструктуризировал раздел Без сноски - контекст "см. подробнее" теряется, кмк
Тут да, в целом проблема - чтоб меньше richfull-текста сделать по всей доке
Ввели по настойчивому предложению одного кортимовца, т.к. без этого неясно "О каком понятии модуля речь? JS-модуля? Так ведь это js-файлы, причем тут это" Но хочется в целом да - соблюдать баланс между тем, чтобы разъяснять контекст, но и не сбивать внимание читателя |
Beta Was this translation helpful? Give feedback.
-
@azinit кажется, это к пункту про форматирование |
Beta Was this translation helpful? Give feedback.
-
Не, мне это не кажется хорошей идеей. Во-первых, потому что мы не можем полагаться на то, что читатели идут по нашему предполагаемому флоу, а не перешли, например, с внешней ссылки. Во-вторых, Введение, будучи обязательным к прочтению всем пользователям, довольно большую цену устанавливает на место внутри себя. Только абсолютно обязательные для понимания методологии вещи должны туда попадать.
Тут та же проблема. На странице нигде не говорится про модули, эта информация теряется за ненадобностью. Там, где есть риск двояко понять этот термин, и должно быть это пояснение. Или на крайний случай выведено в отдельный глоссарий, но это так себе, да и перебор. |
Beta Was this translation helpful? Give feedback.
-
На мой взгляд – это симптом другой проблемы, например, невписанности диаграммы в контент. И мне кажется, что форматирование должно иметь конкретную и, что более важно, объективную причину быть. Если таковой не находится, значит, этого форматирования там быть не должно. Не уверен, насколько это решает проблему холиваров, конечно |
Beta Was this translation helpful? Give feedback.
-
|
Не исключено) Думаю, @RinAkaia была бы того же мнения, что ты описал |
Beta Was this translation helpful? Give feedback.
-
RE: Проблема 5. Сомнительное форматирование текстаTLDR
Знал бы ты, какие были холивары по этой теме внутри кортимы 😄 Но вообще да - щас даже после первой итерации редактуры могут еще находиться моменты, где слишком много редактирования, и слишком мало содержания @illright И если есть еще конкретные замечания - знаешь куда писать) |
Beta Was this translation helpful? Give feedback.
-
RE: Проблема 6. Диаграмма так себеТУт даже спорить не буду, мы того же мнения)) Изначально это вообще был драфт с созвона, но учитывая что не было особо ресурсов на проработку - оставили "as-is" 🤷♂️
|
Beta Was this translation helpful? Give feedback.
-
Чего хотим достичь
На мой взгляд, страница "Введение" должна оправдывать свое название и первую позицию в списке и быть точкой входа в методологию. Для этого от нее требуется:
Скорее всего посетители этой страницы еще не решили, хотят ли они использовать FSD или нет
Не означает, что после нее должна быть только одна страница, а означает, что пользователи должны понимать, какая страница им нужна дальше в зависимости от их потребностей
Проблемы с текущим вариантом
Сначала перечислю для удобства обсуждения, а потом поподробнее опишу каждый пункт:
Небольшая добавочка по своему опыту: я отдаленно помню, каково было начинать входить в FSD с этой документацией, и помню, как ловил себя на мысли, что здесь есть несколько страниц с синонимичными названиями, и они не особо помогают. Иными словами, меня путала структура документации. Поэтому я считаю, что страницей "Введение" ограничиваться не стоит, можно попробовать переработать структуру документации в целом. Но об этом в другой раз.
Проблема 1. Много ссылок
Их много :D. Я, как читатель, только прочитал первые две строчки, а мне уже дали ссылку, которая намекает, что пора бы уже уходить с этой страницы, а то упустишь важный контекст, который нужен для понимания того, что здесь написано.
Два вопроса:
Я догадываюсь, что на самом деле ссылки здесь выполняют не эту роль, а пытаются оправдать громкие заявления типа "проверенных временем". Проблема в том, что это сбивает внимание при чтении, я, как читатель, еще даже не понял, в чем суть, не говоря уже о том, что я не начал сомневаться в написанном.
Что я предлагаю:
Проблема 2. Технический жаргон
Раз уж мы говорим про страницу введения, стоит поставить порог целевой аудитории на уровень "новичок в веб-деве". Здесь, конечно, с разной степенью можно ставить под вопрос существующие формулировки.
Уровень 1. Не очень сильно докапываемся
Второй пункт первого списка перечисляет немало архитектурных принципов. Для тех людей, которые не знают, что это за принципы, возможны два варианта развития событий:
Помните, мы хотели, чтоб страница введения удерживала внимание? Это потому, что они могут и не вернуться, потерявшись во всех этих экспертах, кричащих, что их архитектурный принцип – самый важный принцип. No bueno.
Тех людей, которые знают, что это за принципы, это перечисление заставит задуматься: "Хм, а почему эта методология действительно SOLID? А правда ли в ней есть Separation of Concerns?
А что такое, блин, Vertical Slices". На данном этапе у них еще нет понимания методологии, а значит, нет и базиса, чтоб самим себе ответить на этот вопрос.Что такое бизнес-юниты, которые упоминает третий пункт списка? Он ссылается на какую-то страницу, на которой куча рекламы, а текст – какая-то вода, из которой я так и не понял, что такое Ubiquitous Language. А, стоп, я же хотел узнать, что такое бизнес-юниты...
Много терминов также понаклеены на диаграмме, они понятны тем, кто уже ознакомился с FSD, но на данном этапе чтения Введения – пока еще непонятны. О диаграмме позже еще скажу.
Уровень 2. Очень сильно докапываемся
Рискну предположить, что для кого-то эта фраза может звучать как "FeatureSliced - это _ _ для _ frontend проектов.". Само по себе это не есть плохо, но хорошо бы иметь пояснение этой фразы другими словами, более простыми. Например, вторым предложением сказать "Она регламентирует, как расположить код в проекте, чтоб добиться разделения приложения согласно бизнес-логике и областям ответственности."
Помимо этого в тексте есть определенное количество нераспространенных англицизмов ("онбордить", "детерминированно", "оверхедных"). Опять же, напрямую это не то, чтобы плохо, но лично у меня подобные англицизмы оставляют небольшой осадок непрофессионализма. Думаю, у нас нет цели минимизировать количество слов в тексте, так что мне кажется приемлемым переписать англицизмы на русские аналоги.
Что я предлагаю:
Проблема 3. Смысловое пересечение с другими страницами.
Страница "Введение" это хорошо, но сразу после нее идет страница "Быстрый старт"... "Введение" немного меркнет на фоне быстрого старта, как будто введение – это медленный старт. Более того, по смыслу названий, и то, и другое должно "ввести" людей в методологию, дать им понять, что к чему. Аналогичная проблема наблюдается со страницами "Гайды" и "Справочник". Это претензия не к странице введения напрямую, а скорее к навигации по доке в целом, но решение этой проблемы кроется, в частности, в разделении ответственности между страницами и последующим их переписыванием.
Например, на странице "Введение" мне кажется разумным дать базовое представление структуры проекта, а также какой-нибудь миниатюрный примерчик, а после этого немного поговорить о том, почему это хорошо. При таком раскладе я не вижу особого смысла в странице "Быстрый старт".
Кстати, я вижу на этих страницах тэги "overview-oriented" и "learning-oriented". Для меня как читателя доки нет никакой разницы, куда ориентирована страница, лишь бы она была мне полезна. Из-за этого наличие этих тэгов производит на меня впечатление незавершенной работы над страницей – как будто авторы страницы оставили для себя эти маячки, чтоб держать себя в рамках и не писать оффтоп. Не могу представить, какую полезную информацию эти тэги сообщают читателям, учитывая, что непонятно, какие вообще ориентации бывают, а также куда идти, если ориентация текущей страницы не подходит
Что я предлагаю:
Проблема 4. Отсутствие введения как такового
Я уже говорил выше немного о том, что хочется на странице введения получить представление о том, что именно предписывает методология, а также посмотреть на маленький пример декомпозиции проекта по этой методологии. На данный момент страница введения лишь содержит диаграмму без пояснений (но со ссылкой, которая, опять же, провоцирует прекратить чтение страницы и уйти по ней). В конце страницы, в разделе "Обзор" есть какое-то перечисление вещей, которые я затрудняюсь назвать. Ценности? Принципы? Правила? Вне зависмости от того, как это называется, это не помогает мне понять, что именно предписывает методология, и смогу ли я внедрить ее в своем проекте и команде. Скорее, это содержимое бы больше подошло куда-нибудь под мотивацию.
Что я предлагаю:
Проблема 5. Сомнительное форматирование текста
Тут просто отдельные вбросы:
Тут я предлагаю просто почистить текст от бесполезного форматирования и добавить полезное.
Проблема 6. Диаграмма так себе
Диаграмма эта, помимо того, что она очень простая, из-за чего не очень эстетичная, еще и, кажется, не очень соответствует актуальной действительности. Там представлены не все слои, сегмент
modelsназываетсяmodel, сегментаcomponentsне существует. Надо бы актуализировать ее.Beta Was this translation helpful? Give feedback.
All reactions