Команда платформи інженерії Canonical активно працює над документацією в Rockcraft і Charmcraft, що стосується природної підтримки веб-додатків, таких як Flask і Django. Це частина мети Canonical – писати якісну документацію та постійно її покращувати через процеси дизайну та розробки. Одним із способів покращення нашої документації є залучення членів команди та зовнішньої спільноти. Їхні перспективи та відгуки надають цінну інформацію про дизайн нашого продукту, прояснюють незрозумілі пояснення і покращують користувацький досвід (UX) інструментів.

Ми зосередилися на створенні зручних для користувачів матеріалів – але як ми можемо бути впевнені, що наша документація дійсно користується попитом у читачів?

З листопада минулого року ми тестуємо навчальні посібники для різних фреймворків, проводячи 24 сесії UX (поки що!). Учасники витратили свій час і зусилля на проходження наших навчальних матеріалів, що дозволило нам спостерігати за їхніми спробами і збирати їхні відгуки про інструкції та пояснення.

Вибір учасників для сесій

Ми створили підтримку фреймворків веб-додатків як доступне введення у продукти Canonical через знайомий доступ для більшості користувачів: розробку веб-додатків. Наша мета – залучити широкий спектр користувачів, від досвідчених інженерів до новачків. Для цього ми співпрацювали з нашими внутрішніми командами, такими як Web, які користуються продуктами Canonical щодня, а також зверталися до зовнішніх розробників через онлайн-спільноти та конференції. Щоб наша документація відповідала реальним потребам, ми активно шукали відгуки від тих, хто був незнайомий з Canonical. Ми навіть тестували досвід з університетськими студентами, щоб підтвердити, що він доступний для всіх рівнів навичок.

Сесії

Після набору кожного учасника ми розпочали найважливіший етап: самі сесії. Ми ретельно розробили ці сесії для забезпечення постійного, комфортного досвіду для учасників, заохочуючи їх чесно висловлювати свою думку про все – і будь-що! – в навчальному посібнику.

Типова сесія починається з кількох швидких запитань щодо бекграунду учасника, щоб ми могли контекстуалізувати їхній досвід. Потім ми розпочинаємо навчальний посібник. Ми спостерігаємо, що помічає учасник, як вони інтерпретують інструкції та з якими перешкодами стикаються. Після завершення навчального курсу ми запитуємо набір питань для збору загального відгуку і досліджуємо, чи відповідає інструмент їхнім очікуванням щодо фреймворку.

Що ми дізналися про UX документації

Я відчув весь спектр людських емоцій під час 24 сесій. По-перше, виникає велике відчуття безпорадності, пов’язане з написанням і публікацією документації – як тільки документація потрапляє у світ, я безсилий допомогти моїм читачам! Я виявив, що спостереження за зусиллями користувачів вирішити проблеми, з якими я не міг їм допомогти, виявилося досить складним. На щастя, інженери були там, щоб надати певну допомогу, хоча навіть це не завжди допомагало.

Окрім безпорадності, були також безліч моментів, коли я відчував паніку. Є елемент ризику, пов’язаний з документацією: іноді я виступав за зміни в документації, вважаючи, що вони нададуть кращий UX або зменшать плутанину, але ці зміни в реальному часі викликали збитки. Я навчився зберігати спокій і приймати будь-яку критику щодо змін, за які я боровся. Нові ідеї (принаймні в документації) безумовно варті спроби, але вони стають якісними ідеями лише після підтвердження через UX.

Більшу частину часу сесії були тихими, і я намагався зберігати увагу на учасниках і їхніх діях. Є багато моментів у навчальних посібниках, коли користувачу потрібно чекати – на завантаження програмного забезпечення, на пакування каменів і чарів, на розгортання їхніх додатків тощо. У такі моменти дуже спокуса відволіктися і зосередитися на інших справах, але, як я навчився, важливі спостереження і деталі можуть виникнути в будь-який момент і на будь-якому етапі. Увага, навіть у найнепомітніші моменти, є життєво важливою частиною розуміння досвіду учасників і їх фідбеку.

Учасники надали проникливі відгуки як про інструменти, так і про документацію. Ось деякі з найбільш поширених тем, які ми помітили:

• Під час тестування з університетськими студентами ми виявили, що ці учасники затрималися, коли їх попросили створити новий текстовий файл з терміналу. Ця сесія стала їх першим досвідом використання термінального текстового редактора, і ми не передбачали цей момент у наших інструкціях.
• Учасники, які працювали на ARM64 машинах, зазначили неповний досвід, оскільки пізні частини навчального посібника були сумісні лише з AMD64 машинами.
• Ми виявили кілька спільних моментів, коли учасники пропускали інструкцію, що призводило до проблем. Учасники зауважили, що інструкції здавались “схованими” в тексті і хотіли, щоб навчальний посібник краще підкреслював їх значущість і вплив.
• Зовнішні учасники запитували більше пояснень про продукти Canonical та як працює інструмент – їм було цікаво дізнатися “чому” за навчальним посібником.

Пріоритизація та реагування на зворотній зв’язок

Для кожної сесії ми підсумували всі спостереження в окремі документи. Потім ми зібрали всі прямі відгуки і пропозиції в основний документ; для навчального посібника Flask основний документ з відгуками складає 16 сторінок. Після цього керівник проекту, дизайнер UX, технічний автор (я!) і інженери обговорюємо відгуки, щоб визначити, як їх врахувати. Під час пріоритизації зворотного зв’язку ми враховуємо такі міркування:

• Блокуючі проблеми: Пріоритизуйте відгуки, що вказують на серйозні проблеми.
• Ізольовані інциденти: Визначте зворотний зв’язок, де необхідні додаткові дослідження.
• Дизайнерські компроміси: Реагуйте на зворотний зв’язок на основі конкретних дизайнерських рішень.

Ми вносимо зміни в невеликих партіях з часом, пріоритизуючи важливі блокатори та помилки. Таким чином, ми можемо вирішувати проблеми швидше, що означає, що наші читачі одразу отримують вигоди!

Ми виявили, що зміни, запропоновані раніше UX сесіями, покращили якість і результати пізніших сесій. Загальні проблеми в перших сесіях більше не виникають. Запитання про те, як працює інструмент, піднімаються рідше. І – деякі з вас будуть раді це почути – користувачі з ARM64 машинами можуть пройти весь навчальний посібник.

Приєднуйтесь до нас: допоможіть покращити документацію

У нашій документації завжди є можливість для покращення, і ці сесії UX є чудовим способом включити наших членів спільноти та зробити документацію більш доступною. Якщо ви хочете долучитися, будь ласка, зверніться до нас на нашому публічному каналі Matrix!