Вспомнить Припомнить
Восстановить в памяти сведения, которые невозможно было запомнить: от параметров до кодов ошибок.
Одна из причин, по которой документация сохраняет ценность спустя много лет, — её роль справочника. Мы просматриваем страницы руководств, чтобы вспомнить, извлечь или найти сведения, которые не смогли запомнить: от параметров и кодов ошибок до допустимых значений.
Примеры документации, помогающей вспомнить нужное: справочник Dockerfile и справочник синтаксиса GitLab CI/CD YAML. Они предлагают легко доступную для поиска, хорошо структурированную информацию о фрагментах, которые пользователю нужно вспомнить, чтобы выполнить очередное техническое «заклинание».
Справочная документация — фундамент долгосрочной пригодности продукта. Материалы, созданные ради других действий, пользователь может прочитать один раз и усвоить, а справочные материалы остаются полезными всегда, по мере того как пользователи углубляют знания и берутся за всё более сложные реализации.
Что пользователь хочет сделать
Благодаря справочным материалам документация сохраняет ценность спустя годы. Пользователи просматривают руководства, чтобы вспомнить, извлечь или найти сведения, которые они не смогли запомнить.
Признаки того, что документация этого не обеспечивает
- Пользователи ищут параметр или код ошибки и ничего не находят.
- Справочные сведения разбросаны по публикациям в блогах и журналам чатов.
- У продукта нет доступного для поиска структурированного справочника по синтаксису или настройкам.
Два примера из практики
Распространённые типы контента
| DITA | Diátaxis | Good Docs Project |
|---|---|---|
| <reference>, <refsyn>, <properties> | Справочник | Справочник, Глоссарий |
Одна метрика
доля успешных поисков в справочнике · Доля обращений к справочнику, при которых пользователь получает нужную страницу.