Техническо писане

Документация, написана от продукта, а не от спецификацията

Повечето лоша документация е написана по документ с изисквания или по спомените на разработчик. Тя описва как е трябвало да работи функцията, а не екрана, който потребителят всъщност вижда, с преименувания бутон и допълнителната стъпка за потвърждение. Потребителят следва четвъртата стъпка, не намира нищо съответстващо и отваря заявка.

Изпълняваме всяка процедура в продукта, преди да я опишем, на тестов акаунт, в ролята, която читателят ще има. Когато дадена стъпка се държи различно от очакванията на екипа, я записваме, защото работата по документацията редовно разкрива бъгове, които никой не е докладвал. Този списък често се оказва също толкова ценен, колкото и документацията.

Отделете задачата от обяснението

Потребител, който се опитва да експортира фактура, не иска първо три абзаца за модела на фактуриране. Потребител, който се опитва да разбере модела на фактуриране, не иска номериран списък с кликвания. Смесването на двете в една статия прави и двете по-трудни за намиране и по-бавни за четене.

Разделяме съдържанието на задачи (как да направите едно нещо), концепции (как работи нещо и защо) и справка (настройки, полета, ограничения, кодове за грешки). Всеки тип има свой собствен шаблон, така че страниците остават последователни, след като предадем работата и вашият екип добави четиридесетата статия.

Списъкът с терминология е това, което поддържа комплекта последователен във времето. Ако интерфейсът казва „работно пространство“, документацията никога не казва „проект“ или „акаунт“ за едно и също нещо. Това е малък документ, който предотвратява повечето от объркванията, за които потребителите съобщават.

• Статии със задачи: една цел, номерирани стъпки, резултатът, който потребителят трябва да види
• Статии с концепции: моделът зад дадена функция, с диаграма, където помага
• Справочни страници: всяко поле, настройка и ограничение, в таблица за бърз преглед
• Отстраняване на проблеми: съобщението за грешка, както е написано, причината и решението