Як створювати та оформлювати технічну документацію в IT: рекомендації для початківців і підказки для досвідчених
Мене звати Ірина Ісай, я техрайтерка кіберспортивного медіахолдингу WePlay Esports, частини холдингу TECHIIA. У попередній статті я розповідала про аудит технічної документації, підходи та найкращі практики. Після матеріалу я отримала багато запитань від колег по цеху й тих, хто думає перейти у техрайтинг, як власне писати та структурувати документацію.
Тож у цій статті я поділюся своїм досвідом. Він може бути корисним і для продуктових команд, і для техрайтерів. Не сприймайте поради як правила: це мої власні напрацювання та лайфхаки, які я підглядала в колег.
Ця стаття стане в пригоді як початківцям — людям, які щойно прийшли у професію і хочуть розібратися, з чого починати та яких помилок уникнути, — так і техрайтерам, які вже встигли попрацювати та набити ґуль, яким мій досвід може стати натхненням для пошуку нових рішень у створенні документації. Принаймні я завжди цікавлюсь, як пишуть колеги.
Нижче — про таке:
- з чого починати, коли отримали новий продукт для опису;
- чого точно не варто робити при підготовці документації;
- що робити з документацією, яку писали не ви, але вам ріже очі якість, та чи варто за неї братися;
- трішки про те, якими інструментами користується техрайтер.
«Та що там — просто сісти й написати»
Я страшенно люблю описувати продукти, які ще не описували до мене. У цьому є свої переваги: я сама можу створити структуру документації, скласти правила його форматування і підходи до стилю. Але це не означає, що можна просто сісти перед вікном, яке виходить на океан, і, надихаючись вечірнім бризом, написати роман!
Спершу рекомендую познайомитися з усіма, хто якимось чином долучений до створення та підтримки продукту: поспілкуйтеся, зберіть інформацію, отримайте доступи до продукту, який маєте описати.
Порада. Іноді продуктова команда побоюється давати доступ до самого продукту. Кажуть, що достатньо й тестового зразка. Ніколи на це не погоджуйтесь. Уже не раз мені доводилось переписувати свою роботу, бо, як виявлялось, те, «на чому тестують», і те, що пішло у світ як продукт, — це різні речі. Навіть інтерфейс може дуже різнитись!
А ще продуктові команди часто «експериментують» з найменуванням полів і різноманітних кнопок. Іноді бувають «веселі» назви на межі цензури — у жодному разі вони не повинні потрапити у пристойний мануал продукту! Усі скриншоти робіть лише з гарненько прописаного UI реального продукту, щоб їх було не соромно показати.
Далі перегляньте наявну технічну документацію: юзер-кейси, технічні вимоги тощо. Мені подобається ходити дошками Jira продуктових команд і там збирати інформацію. Усе збираємо, структуруємо (можна навіть у табличку для зручності). Але навіть на цьому етапі, коли здається, що з’явилося якесь розуміння продукту, писати сам мануал зарано.
Коли ви отримали доступи та розібралися з наявною інформацією (або все ще збираєте, адже почали бачити якусь логіку в отриманій інформації), час тестувати продукт.
Наприклад, ISO рекомендує створити профілі своїх читачів:
- Хто користувачі продукту, який ви збираєтесь описати?
- Які завдання вони прагнуть вирішити за допомогою продукту?
- Які є рівні користувачів і як відрізняється доступний для них функціонал?
Техрайтеру потрібно перевтілитись у кожного такого користувача, пройти його користувацький шлях і фактично вирішити ті завдання, які перед ним стоять. Іноді це нудно. Часом доводиться ще раз виконати роботу тестувальника, можливо, навіть прискіпливіше. Але результат того вартий — ваш мануал буде цілісним, немов справжній художній твір: він матиме зачин, основну частину та кінцівку.
Зачин — це окреме рішення. Можливо, потрібно описати спочатку «домашню» сторінку продукту. Іноді логічніше почати з опису кабінету користувача. Не хвилюйтесь, ви зрозумієте це десь на етапі «тестування» продукту. А іноді вам просто скажуть, що наразі потрібно описати ось цей функціонал, а решту потім.
Чого я не роблю: рівні, правила, обіцянки
Не роблю документацію надто глибокою за рівнями. Зі свого досвіду та за порадами колег знаю: якщо ви не Boeing, де кожна стаття може мати підстаттю або допоміжні чи суміжні статті, то ваш максимум —
Бачила приклади, коли для кожної нової фічі продукту техрайтери робили окрему статтю. Не скажу, що це погано, але це слизька дорога. Наприклад, ваш продукт — надто комплексний аналітичний інструмент, який може обростати додатковим функціоналом. Або цей функціонал легко відмирає і замінюється новим. У результаті статей стає так багато, що їх важко знайти в документації. Ба більше — стає важко побачити загальну картину продукту.
Порада. Починайте зі статей вищого рівня — описових, які будуть вступом до мануала про продукт чи гайду про окремий функціонал: ось продукт (функціонал), він такий, робить ось це, корисний тим-то, а користувачі ось такі.
Коли є загальний опис, можна спускатися на нижчі рівні — до конкретного функціонала (чи його елементів). Тут теж для кожного гайда або вже окремих статей має бути невеликий вступ, який роз’яснює, про що користувач прочитає далі.
За можливості я до кожної статті додаю зміст (це можна робити, наприклад, з Confluence) або користуюсь різними рівнями заголовків (наприклад, для PDF). Пам’ятайте: ніхто не буде читати весь мануал і кожну його статтю. Користувач пробіжиться змістом, потім заголовками, можливо, зверне увагу на кольорові блоки з підказками та скриншоти. Але зупиниться тільки на тому, у чому потрібно розібратись.
У кінці кожної статті я ще даю посилання на суміжні матеріали — додатковий або суміжний функціонал. Ніколи не роблю посилань у середині тексту: в PDF не все клікається, в Confluence лінки можуть ламатися, коли потрібно мігрувати на інший райтерський інструмент. Як правило, створюю розділ Read more в кінці гайду й додаю списком кілька посилань.
Коли вже є скелет — верхній рівень документації — і трохи нарощеного м’яса на нижніх рівнях, стає зрозуміліше, де і який функціонал має розташовуватися у документації.
Для роботи з документацією часто використовую Confluence. Тут веду глосарій, таблицю версійності. Для документації добре мати і статтю (окремий документ) про користувацькі та системні ролі — доступи і дозволи у продукті, який ви описуєте
Уже на цьому етапі створення документації починаємо розуміти, як краще називати гайди та статті, навіть заголовки розділів. Головне у назвах — щоб читач інтуїтивно розумів і знаходив потрібну йому інформацію.
Не починаю роботу над документацією без розуміння свого власного стандарту написання. Наприклад, заголовки. Треба вирішити, як саме ви їх пишете: як речення (перша літера велика, інші маленькі); кожна літера велика; використовуєте артиклі чи ні...
Порада. Заголовки — моє улюблене. Часом натрапляю на заголовок-абревіатуру, що й не здогадатися, про що мова. Інколи навпаки — два-три рядки тексту в заголовку — поки дочитав, забув, чого зайшов.
У мене є правило, що заголовок має поміститися в один рядок, а ще краще — у пів рядка. Завжди потрібно пам’ятати, що ваш читач може користуватись пристроями з різним розміром екрана, а текст може мати різні формати: PDF, HTML тощо. Звідси проблема з довжиною рядка та можливістю його дочитати. Його може «з’їсти» поле екрана, а вам потрібно не дратувати читача, а дати йому можливість побачити весь текст одразу.
Я більше пишу англійською мовою, тому намагаюся робити заголовки з активними дієсловами: «видалити__», «створити__». Коли людина шукає відповідь на своє питання, вона має побачити в мануалі конкретну дію, яку треба виконати.
Але не завжди можна поставити активне дієслово. Тоді доводиться робити заголовок більш описовим. Це теж корисно: читач побачить опис, і це допоможе знайти відповідь на проблему.
Форматування заголовків і шрифтів краще виконувати вже після написання основного матеріалу. Для цього чудово мати якийсь інструмент для написання текстів, який дає змогу накладати стилі на всі тексти та коригувати їх централізовано. Поради щодо його вибору напишу нижче у відповідному розділі.
Не описую те, чого не існує. Іноді продуктові команди обіцяють, що ось скоро буде якийсь функціонал, навіть показують його тестовий зразок. А ще можуть пообіцяти виправити, допрацювати щось уже завтра, за тиждень, протягом місяця, що суттєво змінить зовнішній вигляд продукту та його функціонал. Тобто натякають, що це можна вже описати, щоб потім не переписувати. У жодному разі не піддавайтеся! Не можна описувати очікуване. Що на екрані — те в документації.
Робочі моменти
Розповім про кілька складностей, з якими точно стикається кожен техрайтер.
Кнопка є — функції немає. Це поширена історія. Продуктові команди не завжди хочуть вести свою технічну документацію, тож часто пам’ятають лише найсвіжіше про свій продукт. Про нову кнопку розкажуть усе, про сусідню, трохи давнішу, доведеться шукати інформацію деінде. Добре, якщо людина, яка її створювала, ще працює в компанії, бо буває й інакше.
Ще веселіше, коли така кнопка або будь-який інший елемент просто є, але не працює. Можна звернутися до команди, щоб якось їх приховати, випиляти, але це не завжди можливо, не завжди є ресурс. У такому разі я ігнорую елемент, не описую. Хоча залишається ризик, що користувач знайде цей нюанс і почне розпитувати — тоді буде трішки ніяково. Як правило, користувач цікавиться в документації тим, що потрібно вирішити саме йому, і не помічає таких «недоліків». Завдання техрайтера — надати користувачеві корисну інформацію.
Я так спокійно про це говорю, бо продукт — живий організм, він постійно змінюється.
Часом, наприклад, трапляються ще сюрпризи з найменуванням елементів продукту. Працюють собі дві команди паралельно, або одна прийшла відразу після іншої. Вони щось створили, і кожен назвав «оте щось» на власний розсуд. Наприклад, одну й ту саму кнопку одні підписали Add, а інші — Create. Наче й невелика проблема. Але, по-перше, я за консистентність, а по-друге, між цими двома дієсловами велика різниця. У такому разі я пропоную командам дійти згоди та зупинитися на одній назві, додаю їм пояснення з посиланнями на словники, у чому ж різниця.
Я веду невеликий внутрішній канал для команд у Slack, куди можуть підписатися всі в компанії, кому цікаво. Там розповідаю про граматичні й стилістичні деталі, подаю приклади найкращих практик для написання технічної документації.
Приклад рекомендації про різницю слів
Також намагаюся допомогти продуктовим командам WePlay Esports і TECHIIA: створила для них окремий гайд про стиль, абревіатури, граматику тощо. Це прості та стислі замітки, щоб вони могли перевірити себе, якщо є потреба.
Дуже погана документація. Важче працювати з документацією, яку вже написав хтось до тебе. Іноді з документації визирає «кошмар» як за структурою, так і за наповненням. Ймовірно, цьому є пояснення, але не варто витрачати час, щоб у ньому розбиратися.
Частина документації може виявитись корисною. Тож зазвичай я все залишаю без змін, а повертаюся до критично важливих статей та трохи їх приводжу до ладу лише за потреби. Які з них є критичними, можна зрозуміти у процесі користування продуктом. Таку документацію переписуємо, адаптуємо під наявний стиль, щось відправимо до архіву. Виділіть на роботу з уже написаною документацією рік. Так, це справді довго: частковий аудит, відсіювання «кошмарів», архівування некритичних статей (краще іноді описати все знову).
Деколи компанія хоче зберегти попередні версії документації, щоб показати еволюцію продукту. Але навіть для цього процесу потрібно мати інструкцію, як і що архівувати, вести версійність тощо. Звісно, це завдання техрайтера — потрібно мати цілий стосик власних внутрішніх правил і стандартів.
Якщо перед вами стоїть вибір між створенням документації з нуля та всім, що я щойно описала, раджу віддавати перевагу першому варіанту. Є певне задоволення у тому, щоб з нічого створити цілий світ документації. А от розгрібати авгієві стайні — сумнівна радість.
Порада. Якщо у вас багато команд і багато продуктів, можна спробувати застосувати принцип CI/CD (continuous integration/continuous development). Можливо, навіть до роботи з документацією, яку створили до вас.
Я підслухала всю цю історію у свого колеги Девіда Бейлі: він пропонує навчити продуктові команди створювати їхню документацію вже на місцях. Завдання техрайтера тут — контролювати процес, надати рекомендації, стандарти, проводити постійні тренінги, консультувати точково у питаннях, які викликають сумніви.
Документація готується не одночасно на певному етапі створення продукту, а проходить весь цикл його життя. Таким чином вона стає змістовнішою, несе більше корисної інформації
Вибір інструменту для написання документації. Тут йтиметься саме про райтерські інструменти.
Перш ніж щось купувати, треба довгенько попрацювати зі своєю документацією, зрозуміти, як ви пишете, зберігаєте, публікуєте готову документацію, які є вимоги та потреби читача.
Перш ніж придбати свій інструмент, я все спробувала: практично по місяцю користувалася різними програмами, провела декілька демо. Потім усю інформацію зібрала в таблицю, розібрала переваги й недоліки та в результаті зупинилася на MadCap Flare.
Якщо буде запит, розкажу, як і серед чого обирала — переваги, недоліки, власні міркування щодо кожного протестованого інструменту. Напишіть про це в коментарях.
Скрин програми MadCap Flare
І ось я щаслива переношу всю документацію у MadCap Flare. Тут ми робимо таке:
- пишемо абсолютно всі статті — їх ми теж публікуємо у Confluence для продуктових команд, а ще це певний «бекап» інформації;
- централізовано створюємо стилі та форматуємо тексти (зазвичай це формати PDF, HTML5);
- ведемо свій глосарій з визначеннями;
- обов’язково підтримуємо «змінні» — загалом це власні назви, які ми вводимо за допомогою глосарію. Їх можна зручно з одного джерела замінити у всіх мануалах, якщо раптом виникне потреба;
- обов’язково для роботи в такому інструменті маємо спеціальний гайд, який визначає всі критичні питання: стиль, граматика, робота з візуалізацією тощо.
Рекомендації для початківців
У нашій частині світу техрайтерство — ще молода професія, вона тільки формується. Іноді на різних ІТ-ресурсах навіть немає такої категорії, щоб відфільтрувати за вакансіями чи подивитись статистику щодо зарплати. Тому важко знайти «галузеві» стандарти, а кожен техрайтер може експериментувати на свій страх і ризик.
Перша порада — шукати найкращі практики, читати мануали компаній з історією та репутацією. У них техрайтерська традиція давно склалася. Там працюють цілі відділи, озброєні своїми внутрішніми стандартами та політиками. Кожне їхнє рішення для документації давно обґрунтоване, логічне. Ти як машина — пишеш те, що сказали, і так, як написано в інструкції. У цій ситуації немає місця для власного бачення, але саме за такими компаніями раджу підглядати в пошуку свого стилю.
Як приклад наведу Google developer documentation style guide. Зокрема, докладне роз’яснення щодо вживання слів.
Google ще й пропонує цікаві курси з техрайтингу для розробників, але вони будуть корисні всім: Technical Writing One; Technical Writing Two
Друга порада, яка вже звучала, — спершу розібратися в продукті, сформувати архітектуру документації, створити свої стандарти та прописати для себе правила її написання.
Мене часом просять: покажи, як у тебе. По-перше, не все можна показувати. Якщо документ не міститься у відкритому доступі, найімовірніше він конфіденційний. По-друге, користі з цього ніякої — іншому техрайтеру це не допоможе, бо в кожного свої користувачі й вони мають власні потреби. Просто «списати» не вийде.
Третя порада — не копіювати, а шукати власний підхід. Працювати на ринку з несформованою техрайтерською традицією означає самому долучатися до формування правил гри. І в цьому є свої маленькі радощі.
Маленький тест на техрайтера
На завершення хочу сказати, що не все так страшно. Робота з документацією — цікава, якщо ваші душа та мозок налаштовані на структурування будь-якої вхідної інформації. Але якщо людина вважає себе техрайтером тільки через те, що вміє писати англійською мовою, — маю розчарувати. Наша професія досить нудна, потрібно вміти всістись і детально розібратися з продуктом; вимагає багато зусиль і часу на саморозвиток, а це безперервний процес.
Добрий техрайтер — той, хто зважає на деталі та шукає можливість задокументувати належним чином будь-що. Наприклад, як зробити скриншот зі Smart TV без спеціального пристрою? Добре, якщо ви працюєте у Samsung і у ваших руках є безліч інструментів. А тим, хто подумав про фото екрана телевізора, зроблене на телефон, наразі відмовлено в доступі у світ інструкцій, гайдів і мануалів.
Якщо ж ви читаєте інструкцію до нового гаджета, помічаєте недоліки й хочете її переписати просто зараз — ви пройшли тест на техрайтера! Велкам до нашого ком’юніті.
Додам тут свої улюблені READ MORE. Список можна продовжити — ці посилання лише для натхнення:
