aaa
Обслуживание аудитории системы с хорошо организованным контентом Автор: Натан Кертис Часть 1: Обзор
Высококачественная документация по компонентам является отличительной чертой эффективной библиотеки. Мы надежно описываем каждый компонент пользовательского интерфейса, стремясь стимулировать принятие эффективных проектных решений и ускорять разработку. Хорошая документация не бесплатна. Нужно планирование, усилия и процесс, чтобы сделать примеры и руководства, которые меняют ситуацию к лучшему.
Начиная с этого, эта коллекция из шести статей охватывает историю документирования компонентов. Я начинаю со стратегии аудитории, контента и архитектуры. Затем я расширяю цикл статей введением, примерами и руководством по проектированию и коду, и заканчиваю процессом. Советы отражают то, чему я научился за годы и вдохновлен тем, чем сегодня публично делится наше сообщество.
И поэтому я начинаю с вопроса: для какой аудитории предназначен этот документ, какой контент ему нужен и как мы оптимально организуем страницы для его передачи?
Для начала: для кого это? А поскольку ответ обычно охватывает не одну дисциплину, то вопрос еще может быть таким: кто важнее?
Когда библиотека представляет код, инженеры являются аудиторией. Очевидно. Если библиотека - это только код, должна ли документация обслуживать и дизайнеров? Если документация предлагает только руководство по проектированию без кода (например, Google Material), нужно ли это инженерам?
In my opinion, in both cases, yes. Absolutely, yes. Component documentation must serve both audiences, always, to varying degrees.
Кроме этого, может ли быть документация для кого-нибудь еще? Возможно, тем более, что система тесно связана с тем, как работают команды. Мощные, содержательные введения привлекают внимание менеджеров по продуктам. Примеры реализации показывают состояния для QA специалистов. Стиль, поведение и редакционные аспекты направляют исследователей и специалистов по контент-стратегиям.
Многие системные команды также публикуют систему в качестве публично видимой для сообщества. Хотя по своей природе они стремятся делиться информацией, внешне они оправдывают создание видимого сайта в качестве инструмента для набора персонала. Система должна демонстрировать строгость и качество, мастерство и сотрудничество, практику, повышенную настолько, что талантливый рекрутер видит силу.
Основная цель документации остается неизменной: оснастить специалистов-практиков - инженеров, конструкторов и всех остальных - для эффективного и результативного использования системы. По мере роста она может обслуживать многих, несмотря на их различные потребности и частоту использования.
Обслуживать каждого не значит обслуживать каждого в равной степени. Инженеры могут посещать документацию 5, 10 и даже больше раз в день. Это может быть даже открытое окно, примыкающее к их редактору кода! Дизайнер может посещать его реже, сравнивая с этим и иногда увлекаясь деталями. Контент-стратег или исследователь могут посещать редко, чтобы поддержать решение.
Итак, кто важнее всего? Мой опыт подсказывает четкую стартовую точку: системы создаются в первую очередь для/о инженеров и дизайнеров. В то время другие радостно вносят свой вклад и приносят пользу, но они вторичны. Обслуживание вторичной аудитории менее чем оптимально может быть необходимым компромиссом. Если мы сэкономим на инженерах или дизайнерах, это будет проблемой. Большой проблемой.
А как же инженеры против дизайнеров? Каждая система, над которой я работал в последнее время, служит и тому, и другому, направляя и дизайн, и код. Некоторые документации, которые я наблюдаю в других организациях, отражают сильную предвзятость по отношению к одной или другой группе, или разделяют назначения для каждой из них (подробнее об этом позже). Есть много аспектов, которые необходимо учитывать: ваши цели, частота использования, глубина содержания, качество, стоимость производства контента и актуальность для их работы.
Я дизайнер. Но я также прагматик. Если бы мне пришлось выбирать, без всякого контекста, я бы отдал предпочтение инженерам. Иметь 50 инженеров которые кодят хорошо спроектированные компоненты с большей вероятностью приведет к цельному результату, по сравнению с 50 дизайнерами, которые читают тома инструкций о решениях, уже встроенных в этот код.
На заметку: Приоритет аудитории зависит от многих факторов. Ожидайте, что дизайнер и инженер должны столкнуться, и попытаться оптимизировать для обоих. Если вы не можете это обеспечить, ориентируйтесь на компромиссы с теми, кто использует материал, наиболее близкий к конечному продукту, как правило, код. Это означает, что, во-первых, инженеры, во-вторых, дизайнеры.
Документация компонентов соединяет вашу аудиторию с контентом, который вы можете предоставить. Контент принимает различные формы, они не все стоят одинаково, и вы должны сплести их вместе.
На высоком уровне компонентная документация обычно включает в себя эти четыре типа:
- Введение в названия компонента и краткого описательного содержания, задающего тон тому, что там есть. (И требуется)
- Примеры иллюстрирующие вариации названных компонентов, состояния и другие измерения. Предпочтительна иллюстрация в паре с отрендеренным кодом, вместо обычной статической картинки.
- Дизайн референс, включаяющий в себя: когда использовать, когда не использоваться. Примеры когда делать и когда не делать. Гайдлайны для визуальных, интерактивных и редакционных аспектов.
- Код референс, подробно описывающая API кода (например, Props) и другие вопросы реализации. (Требуется, если код существует)
Введение должно быть быстрым и дешевым, отрывая пример для написания предложения или двух. Хорошо организованные Примеры являются важными инвестициями, которые со временем становятся предсказуемыми. Код референс должен появляться с помощью простых и кропотливых шаблонов, которые инженеры используют, чтобы заполнить пробелы.
Но сделайте глубокий вдох. Эффективный дизайн референс может быть очень дорогим, организуйте только базовые вещи, либо пропустите их полностью. Дизайн нарратив зависит от целей системы, возможностей и таланта команды, а также от аппетита сообщества.
На заметку: Компонентная документация может включать в себя широкий спектр контента. Поэтому начните обсуждение сверху, чтобы пробудить в команде ценности и обсудить типы инструментов для представления материалов, которые дизайнеры и инженеры могут различать (код референс против дизайн референса), места пересечения, или обмен (примеры, включая наименование, содержание и порядок).
На практике, Компонентная документация может возникать как из преднамеренного выбора, так и из неблагоприятных ограничений. Часто, компонентный документ заканчивается раздельной историей: дизайнеры публикуют для дизайнеров здесь, инженеры публикуют для инженеров там. Эта фрагментация может произойти случайно, в результате проектирования, или и того, и другого. В результате заранее обсуждается информационная архитектура страницы компонентов.
Документация Google Material иллюстрирует фрагментацию. Основа Material Design возникла еще до ее внедрения - от Material Design Lite и Polymer Project до раздела Android Developer's design section и Material UI (build for React). В этих реализациях имеется свободная ссылка на родительский проект, который остается свободным от проблем, связанных с кодом.
Эта фрагментация не просто необходима, она значима и оправдана. Material распределен по фреймворкам, командам, платформам и - давайте будем честными - мир сегодня превосходит все другие системы проектирования на практике.
Для всех остальных, дизайн идет сюда, инженерия идет сюда, ментальность общая. Это намерение фокусируется на содержании по дисциплинам, оптимизируя процесс чтения для каждой аудитории в отдельности.
Разделение дизайн/код тоже несет в себе риски. С течением времени, сайты выпадают из синхронизации как:
- Таксономии расходятся (даже для простых имен, таких как «loader» и «spinner»).
- Фичи расходятся: дизайн выражает глубокие недостижимые в коде фичи, или код артикулирует недодизайненым результатом.
Отсутствие соглашения кажется нормальным. Истории разные, да? Ну, по крайней мере, они удобно разделены для авторского процесса.
Тем не менее, усыновители тоскуют по единому источнику правды. Те, кто интересуется обеими историями, попадают на теннисные соревнования, перескакивая туда и обратно. Полезные детали существуют в обоих местах, архитектурно ясно, как повествовано усыновители должны связать себя воедино.