https://documentation.divio.com/
руководство пользователя
- не должна быть описанием апи
- надо отталкиваться от задач пользователя
туториал
- продающий жанр
- для кого
- обучение новых пользователей (create your first application)
- сценарий эвалюатора (тот, кто решает, покупать или нет)
- обучение сущ пользователей новым
- как делать:
- все шаги верифицированы и работают
- должен содержать минимально необходимую информацию
- как будто пишешь для маленького ребенка (надо дать человеку простой работающий сценарий)
- должен рождать в человеке чувство успеха (ура, получилось)
справочное руководство (reference)
- фокус на информацию
- структура и консистентность
- точным, актуальным
сообщение в продукте
хороший технический текст
- понятный
- достоверный
- полный
- лаконичный
как сделать понятным:
-
тон
- спокойный, нейтральный
- без жаргонизмов и локальных мемов
- активный залог, личные меcтомения, повелительное наклонение ("сделайте", "вы", а не "фича может быть использована") - формирует чувство успеха
- утверждение, а не отрицание ("мы поддерживаем Х, а не "не поддерживаем Y")
- настоящее время
- дефолтные значения выделить отдельным предложением
-
процедуры и концепции процедура
- решает некоторую конкретную задачу
- описывает законченное действие
- содержит несколько последовательных шагов
- может содержать примеры и иллюстрации концепция
- повествовательное описание идеи
процедуры и концепции дополняют друг друга, их можно (и нужно смешивать)
-
описание кода
- все, чего нет в языке, стоит выделить monospace
-
важность структуры Туториал: Заголовок Цель, задачи Процедура Шаг Шаг Процедура Шаг Шаг Итог
-
вычитка текста этапы ревью
- use-case review проводится экспертом, отвечающим за предметную область выработка стратегии для документирования функционала
- tech review факт чекинг код работает код красивый
- editorial/peer review
кто-то чекает стиль повествование
чек-лист для peer review (у коллеги)
- здравый смысл
- структура
- форматирование
- стиль
- опечатки
- в идеале еще верификация
- qa review на чистой машине чекается по шагам
-
больше смыслов, меньше слов
-
язык должен быть прост и изящен