Засновник агентства EightShapes Натан Кертіс в своєму блозі на Medium розповідає як зробити документовані компоненти зрозумілими та корисними і для розробників коду, і для дизайнерів, і для всіх інших.
Telegraf.design переклав першу з циклу статей, в якій йтиметься про стратегію визначення аудиторії, а також про контент та архітектуру. Ці поради ґрунтуються на досвіді Натана за роки практики та підходах, якими користуються інші спеціалісти цієї сфери сьогодні.
Якісно документовані компоненти — показник зручності бібліотеки. Ми детально описуємо кожен елемент користувацького інтерфейсу, щоб дизайн-рішення були ефективними, а розробка швидкою. Розробити якісні документи непросто. Щоб підготувати дійсно корисні приклади та інструкції, треба все спланувати, докласти чималих зусиль та витратити багато часу.
Почнемо з таких питань: для якої аудиторії створюється документ, який контент їй потрібен та яким оптимальним чином вибудувати архітектуру сторінок так, щоб якісно передати весь той контент?
Аудиторія
Спочатку визначаємо — для кого то все? Цільова аудиторія частіше за все включає представників кількох сфер, але які з них важливіші?
Інженери, дизайнери та всі інші
Якщо бібліотека містить код, її аудиторія — інженери. Це очевидно. Якщо бібліотека містить лише код, чи має цей документ орієнтуватися на дизайнерів також? Якщо документ пропонує гайд з дизайну без коду (наприклад, Google Material), чи має він бути зручним та зрозумілим для інженерів?
На мою думку, в обох випадках відповідь «так». Абсолютно точно «так». Документуючи компоненти, ви маєте орієнтуватися на обидві аудиторії, але в різних обсягах.
І не виключно на ці дві аудиторії. Коли в системі взаємодіють декілька підрозділів, документовані компоненти стосуються їх всіх. Сильні та змістовні вступи корисні продакт-менеджерам. Приклади ілюструють певні стани, і ця інформація потрібна QA-спеціалістам. Стиль, поведінка та текстове наповнення цікавлять дослідників та контент-стратегів. Спеціалісти з доступності прийдуть сюди за своїми гайдами — і лише подякують вам, якщо вони будуть зручними.
Дизайнер — Інженер — Продакт-менеджер — Доступ — Тестування — Дослідження — Контент
Багато команд роблять свою систему видимою для всієї професійної спільноти. Їм хочеться поділитися своєю роботою з іншими — але це поверховий мотив. Насправді ж видимий сайт фактично стає професійним резюме. Він дозволяє оцінити технічну виваженість, стрункість та якість системи, рівень експертизи команди, вміння співпрацювати та ступінь професіоналізму. Рекрутер відразу зчитує всі ці характеристики.
Але про головну ціль документації ніхто не забуває. Вона в тому, щоб допомогти інженерам, дизайнерам та всім іншим користуватися системою ефективно. У міру свого розвитку документація може стати у пригоді багатьом спеціалістам, попри те, що вони переслідують різні цілі та використовують систему з різною інтенсивністю.
Підсумок: дизайн-системами все частіше користуються команди з різних професійних ніш, не лише дизайнери та інженери. Якщо ви хочете масштабуватися, варто створювати контент, який буде зрозумілим та зручним для широкої аудиторії.
Інженери, дизайнери, а вже потім — всі інші
Орієнтуватися на всіх не означає орієнтуватися на кожного рівною мірою. Інженери можуть відкривати документ по 5-10 разів на день, якщо не частіше. А деякі з них взагалі триматимуть вікно з документом відкритим поруч з редактором коду. Дизайнеру документ буде потрібний час від часу — щоб порівняти якісь моменти та вчитатися глибше. Контент-стратег або дослідник зайдуть ще рідше — щоб знайти якусь інформацію, необхідну для прийняття рішення.
Так хто ж тут головний? Мій досвід підказує, що першочергово системи розробляються інженерами та дизайнерами — на основі їхньої експертизи, ними та для них. Інші роблять свій вклад та допомагають, але вони вторинні. Інколи доводиться в певній мірі нехтувати інтересами вторинної аудиторії. Але якщо ми поступимося інтересами інженерів або дизайнерів, це обернеться проблемою. Великою проблемою.
Первинні: Дизайнер — Інженер
Вторинні: Продакт-менеджер — Доступ — Тестування — Дослідження — Контент
А якщо треба обрати, кому робити зручно: інженерам або дизайнерам? Кожна з систем, з якими я працював останнім часом, орієнтується на обидві групи. В документах деяких інших організацій просліджується чітка прив’язка до першої або другої групи — або жорстке розділення в стилі: «ось це для цих, ось те для тих» (про це згодом). На цей вибір впливає багато чинників: ваші цілі, частота використання першою чи другою групою, глибина контенту, якість, ціна виробництва контенту та відповідність профілю першої або другої групи.
Дизайнер vs Інженер
Я дизайнер. І прагматик. Якщо обирати одну з категорій — без контексту, — я за інженерів. Якщо 50 інженерів будуть кодувати компоненти з якісним дизайном, є більше шансів, що ми отримаємо міцно збудований, грамотно зібраний продукт, ніж коли 50 дизайнерів будуть вчитуватися в добірки гайдів щодо рішень, вже вбудованих в цей код.
Підсумок: на визначення пріоритетної аудиторії впливає багато чинників. Ймовірніше за все, потреби дизайнера та інженера будуть збігатися, тож спробуйте оптимізувати документ для обох. Якщо це неможливо, акцент треба робити на тих, хто працює з матеріалом на етапі, найближчому до випуску — зазвичай, це розробники коду. Тобто спочатку інженери, потім дизайнери.
Контент
Компонентний документ зв’язує аудиторію з контентом, який ви можете дати. Контент може існувати в багатьох формах, вони мають різне значення та вагу. І вам вирішувати, як саме ці форми переплести.
Вступ — Приклади — Дизайн-референс — Код-референс
Якщо узагальнити, компонентні документи зазвичай бувають чотирьох типів:
- Вступ до назви компоненту та стислий опис, який задає тон всьому, про що йтиметься мова. (Необхідно)
- Приклади, що ілюструють названу варіацію компонента, його стани та інші виміри — все це краще описувати кодом, а не статичною графікою. (Необхідно)
- Референси щодо дизайну, які містять гайди типу «Користуватися, коли», «Це можна, це не можна», гайди щодо візуальної частини, взаємодії та редакційних очікувань. (Рекомендовано)
- Референси щодо коду, які описують API (прикладний програмний інтерфейс) коду (наприклад, «Властивості») та інші питання щодо імплементації. (Необхідно, якщо є код)
«Вартість» виробництва контенту залежить від його типу
У кожного контенту своя «вартість». Вступ має бути швидким та «недорогим», тобто нескладним з точки зору виробництва. Він має містити простий та зрозумілий приклад з одним чи двома реченнями. Добре організовані приклади дуже важливі, з часом створювати їх стає все легше, вони стають «передбачуваними». Референси з Коду мають з’являтися у максимально простих та ясних, хоча й нудних шаблонах, якими інженери користуються для внесення максимальної ясності в свій робочий процес.
Вартість виготовлення: Дешево / Дорого.
Деталізація: Поверхнево — Глибоко.
Вступ / Дизайн/ Приклади / Код
А зараз я скажу щось не дуже радісне. Корисний Дизайн-референс може коштувати дуже «дорого», тому автори системи часто обмежуються лише базовою інформацією або взагалі пропускають цей пункт. Описи щодо дизайну залежать від цілей системи, здібностей та талантів команди і стандартів спільноти.
Підсумок: компонентний документ може містити безліч типів контенту. З самого початку обговоріть цінності команди та з’ясуйте типи контенту, які дизайнери та інженери будуть споживати окремо (референс щодо коду чи дизайну), які будуть накладатися один на одного (інтро) чи споживатися колективно (приклади, що включають назви, контент та послідовність).
Створення архітектури компонентної сторінки
Дизайн та код: розділяти чи об’єднувати?
На практиці компонентні сторінки — це результат ретельно обдуманого вибору та обмеження одного заради іншого («прибрати це негайно!» — «ні, це!»). Компонентна сторінка може існувати в двох версіях: дизайнери створюють її для дизайнерів та публікують тут, інженери — для інженерів та публікують там. Ця фрагментація може виникнути випадково, за задумом або за обох причин. Тому я рекомендую обговорювати архітектуру інформації на компонентній сторінці ще на початкових етапах.
Екосистема Google Material чудово ілюструє таку фрагментацію. Дизайн-база Material з’явилася задовго до своїх імплементацій у різних формах — від Material Design Lite та Polymer Project у дизайн-категорії Android Developer до Material UI (створеному для React). Ці реалізації слабко пов’язані зі своїм «дизайн-джерелом», яке й досі абсолютно не обтяжене кодом.
Дизайн компоненту — Код компоненту — UI демоверсій — UI API
Вступ — Приклади — Дизайн — Код
Google Material повторює контент в Material Design, Material Design Lite, а також в Demos та API Material UI.
Така фрагментація не просто істотно важлива — вона має сенс та солідне обґрунтування. Поширенням, яке Material має серед фреймворків, команд, платформ та — будемо чесними — взагалі усюди, не має жодна інша дизайн-система в світі. Але! Ми не намагаємося бути Google Material!
З точку зору всіх інших, дизайн має йти окремо, а розробка окремо. Цей підхід дозволяє розподілити контент за профілем, оптимізуючи процес читання для кожної з профільних аудиторій.
Сайт про дизайн / Сайт про код
Сторінка компоненту / Сторінка компоненту
Вступ / Приклади / Дизайн / Код
Компонентний дизайн-гайд та документи з кодом та API, вільно поєднані на різних сайтах. Приклад: Atlassian.
Відокремлення дизайну від коду та навпаки має свої ризики. З часом контент у різних розділах перестає узгождуватися через те, що:
- Відрізняється класифікація та систематизація (навіть таких простих назв, як «індикатор завантажування» та «спіннер»).
- Відрізняються характеристики: дизайн описує складні характеристики, які неможливо скодувати, а код формулює результати, яких неможливо досягнути завдяки дизайну.
Брак узгодження між цими напрямками — це нормально. Різні сфери, різні погляди. Головне, що вони якнайменше зручно розділені для оптимального робочого процесу.
І все ж таки ті, що користуються системою, хочуть мати одне єдине «джерело істини». Ті, кому важливі обидві теми, відчувають себе наче на тенісному корті — бігають туди-сюди, сюди-туди. Корисні деталі є і там, і там, їх помітно, але користувачі — ті, хто далі створює наратив — мають поєднувати їх самостійно.
Підсумок: Будьте обережні з цим розділенням на «дизайнерське» та «кодове». Автору простіше опублікувати контент як є, але згодом це призводить до проблем, які перекреслять всю користь. Сам факт існування таких паралельних сайтів також може вказувати на неприємний розкол між дизайнерською та інженерною частиною.
Що краще для поточного контенту — стек чи вкладка?
У багатьох системних програмах, якими я керував в останні роки — наприклад, Morningstar Design System, ми ставили дизайн та код в один потік. Так користувачі можуть бачити уніфіковані назви, гайди та пояснення щодо використання варіацій та функцій.
Одна сторінка: приклад стеку, з дизайном та кодом
Вступ — Приклад — Дизайн — Код
Сторінка компонентної документації, на якій інформація про дизайн та код подається разом — скролиш та читаєш, як у Morningstar Design System.
Сторінка з поточним контентом має свої мінуси: вона довша, тому що там зібраний контент за різними напрямками. У якості альтернативи інші системи після вступу подають різний за профілем контент у різних вкладках.
Одна сторінка: приклади, вкладки з дизайном та кодом
Вступ / Приклад / Дизайн / Код
Підсумок: Змішувати дизайн та код можливо. Команда може обрати UI — потік, вкладки або щось інше, що максимально відповідає її інтересам.
Групування та впорядкування контенту за типом
Незалежно від типу впорядкування — потік або вкладки, — я завжди раджу впорядковувати контент послідовно та з пріоритетним викладенням інформації у:
- Вступу.
- Прикладах — найголовніші, які цікавлять більшість, розташуйте спереду по центру.
- Дизайн-гайдах, що розширюють приклади та перетворюються на справжні розповіді великого обсягу.
- Референсах щодо коду, які логічно та передбачувано структуровані та де одна частина залежить від іншої. Якщо в пріоритеті інженери і головне — це Властивості, треба підняти довідкову таблицю туди, де вона буде максимально помітною.
Приклади рулять, і допоки користувач знаходиться на відстані в один клік від деталізованих та глибоких дизайн- та код-референсів, все у вас буде добре. Але — і це цікаво — в різних системах інформація відносно дизайну та коду часто має несистематизоване маркування та викладається в різному порядку.
Різні підходи, які відрізняються по тому, який контент в пріоритеті: Код (в Прикладі) перший, Дизайн перший або текстовий приклад над всіма вкладками.
IBM Carbon поважає приклади та насамперед описує Код, а деталі щодо Використання та Стилю вказує у наступних відповідних вкладках. В системі Hudl’s Uniform зворотній пріоритет — там Дизайн йде першим, а вже потім Код. Про код йдеться у наступній вкладці з класифікацією та систематизацією, дуже схожою — проте не тією ж самою. Lightning Design System від Salesforce робить приклад у формі тексту, що слугує провідником по компонентах над вкладкою Керівництво для розробників. При цьому Примітки щодо імплементації та Керівництво з дизайну чомусь залишаються пустими.
Залежно від організації, додаткові частини — найчастіше, Доступність — розташовуються паралельно, частіше за все перед або після вкладки Дизайн.
Підсумок: Почніть зі Вступу та акцентуйте Приклади. Пріоритет гайдів з Дизайну або Коду залежить від самої організації та того, наскільки вона цінує ту чи іншу аудиторію та любить доносити інформацію розлого та з подробицями.
На довгих сторінках розташуйте якорі для навігації
Чим довша ваша сторінка, тим важливіше чітко вказати, що на ній та де саме ви знаходитеся зараз. Використовуйте вертикальну локальну навігацію з прокруткою праворуч: вона вказує, де саме на сторінці знаходиться користувач, та показує підзаголовки під час скролінгу.
Ілюстрація: Morningstar Design System оптимізує локальну навігацію за допомогою правої колонки з двома ієрархічними рівнями
Підсумок: дизайн інтерфейсу користувача — у всіх вкладках або на одній сторінці з прокруткою — залежить від вашого смаку. На багатьох сайтах є постійна вертикальна навігація. Поцікавтеся в своєї аудиторії, що їй зручно, досконало вивчіть свій контент, доводьте зручність використання до найвищого рівня і завжди пам’ятайте: назви розділів та порядок мають бути тими ж самими по всій бібліотеці.
Показувати дизайн ЧИ код ЧИ обидва?
Чим тісніше переплетені дизайн та код, тим більше дизайнерів та розробників коду попросять перебудувати інтерфейс сторінок відповідно до їхніх цілей та інтересів.
Дизайн-менеджер спитає:
— Чи можна сховати всі приклади та довідкові таблиці про код?
Інженер спитає:
— Чи можна позбавитися від всіх детальних описів про дизайн?
Є вихід: використовуйте кнопку-перемикач, щоб можна було ховати інформацію про дизайн або код. Для цього треба мати чітко класифікований контент і визначити, до кого відноситься кожна його частина — до першої групи, до другої групи чи до обох.
Ось як варто зробити:
- Завжди показуйте вступ, марковані приклади та все, що стосується доступності.
- Режим «Виключно дизайн» може приховувати спіпети коду та деталізовані технічні інструкції — наприклад, таблиці із Властивостями або модифікатор класів CSS.
- Режим «Виключно код» може приховувати довгі описи про візуальний стиль та редакторські поняття, але показувати інші керівництва — наприклад, «Використовуйте, коли», — релевантні для інженерів.
Наприклад, Hudl’s Uniform використала кнопку-перемичкач, яка допомагає зорієнтувати користувачів в одну чи іншу тему:
Дизайн-система Hudl’s Uniform розділяє гайди щодо Дизайну та Коду з допомогою перемикача, який змінює всю сторінку відповідно (у верхньому правому куті)
Реалізація тут дуже приємна та зрозуміла, але «недешева»: непросто зробити якісний UI та ефективно впорядкувати контент. Деякі клієнти, з якими я працював, також розділяли контент, але трошки іншим чином, дуже розумним: вони окреслили межу між дизайном та розробкою, проте зробили її прозорою.
Підсумок: Фільтрація за типом контенту — це більше питання контент-менеджменту, а не технічної реалізації.
Чим жорсткіша ваша інформаційна архітектура, тим легше зробити такий розподіл. Але все залежить від якісної роботи автора та вміння відокремити питання, які можуть цікавити обидві групи.
Тепер ви відчуваєте аудиторію, знаєте, який контент треба зробити, та згодні з необхідністю провадити високорівневу структуру. Час братися за роботу.
Оригінал статті доступний за посиланням.
Переклад: Ганна Руденко.