Справочник¶
Справочники — это технические описания устройства системы и способов работы с ней. Справочная документация ориентирована на информацию.
Справочная документация содержит пропозициональные, или теоретические, знания, к которым пользователь обращается во время работы.
Единственная цель справочника — давать как можно более краткое и упорядоченное описание. Содержание учебных и практических руководств определяется потребностями пользователя, а содержание справочника — самим описываемым продуктом.
В случае программного обеспечения справочники описывают саму систему — API, классы, функции и так далее — и способы работы с ними.
Пользователям нужна справочная документация, потому что во время работы им необходимы достоверность и определённость — твёрдая опора. Хороший технический справочник даёт им уверенность, необходимую для работы.
Справочник как описание¶
Справочная документация описывает устройство системы. Она должна быть строгой. Её почти не читают — с ней сверяются.
В справочной документации не должно быть сомнений или двусмысленностей: она должна быть полностью авторитетным источником.
Справочная документация подобна карте. Карта сообщает всё необходимое о местности, избавляя вас от необходимости исследовать её самостоятельно. Справочник выполняет ту же задачу для продукта и его внутреннего устройства.
Справочная документация не должна учить выполнению задач, однако она может — и часто должна — описывать, как что-либо работает или как этим правильно пользоваться.
Некоторые справочные материалы, например документация API, могут создаваться автоматически самой описываемой системой. Это действенный способ поддерживать документацию в точном соответствии с кодом.
Ключевые принципы¶
Только описывайте¶
Нейтральное описание — главный принцип технического справочника.
К сожалению, нейтрально описать что-либо — одна из самых сложных задач. Для человеческого общения это неестественно. Гораздо естественнее объяснять, наставлять, обсуждать и высказывать мнения, но всё это противоречит задачам технического справочника, который требует достоверности, точности, полноты и ясности.
Возникает соблазн добавить инструкции и объяснения: само по себе описание может казаться недостаточно полезным, а эти материалы действительно нужны. Но вместо этого дайте ссылки на практические руководства, объяснения и вводные учебные руководства.
Придерживайтесь стандартных форматов¶
Справочная документация полезна, когда она единообразна. Стандартные форматы позволяют эффективно ею пользоваться. Ваша задача — поместить нужный пользователю материал туда, где он ожидает его найти, и представить в привычной форме.
В текстах хватает возможностей порадовать читателя богатым словарным запасом и владением разными стилями, но справочная документация для этого совершенно не подходит.
Следуйте структуре системы¶
Соответствие карты изображённой на ней местности позволяет ориентироваться с её помощью. Так же должно быть и с документацией: структура документации должна отражать структуру продукта, чтобы пользователь мог одновременно ориентироваться и в продукте, и в его описании.
Это не значит, что документацию нужно втискивать в неестественную структуру. Важно, чтобы логическая и концептуальная организация кода и связи внутри него помогали понять устройство документации.
Приведите примеры¶
Примеры наглядно помогают читателю понять справочный материал, не отвлекая автора от задачи описания. Например, короткий пример использования команды может показать саму команду и контекст её применения, не превращаясь в объяснение или инструкцию.
Язык справочников¶
- Стандартная конфигурация логирования Django наследует стандартные настройки Python. Она доступна как
django.utils.log.DEFAULT_LOGGINGи определена вdjango/utils/log.py. Излагайте факты о системе и её поведении.
- Подкоманды: a, b, c, d, e, f.
Перечисляйте команды, параметры, операции, возможности, флаги, ограничения, сообщения об ошибках и так далее.
- Используйте a. Не применяйте b, если не выполнено c. Никогда не делайте d.
Добавляйте необходимые предупреждения.
На примере еды и кулинарии¶
Чтобы решить, как поступить, можно свериться с информацией на упаковке продукта.
Когда вы ищете информацию — относящиеся к делу факты, — вам не нужны мнения, догадки, инструкции или интерпретации.
Вы также ожидаете, что информация будет представлена стандартным образом. Тогда сведения о пищевой ценности продукта, условиях хранения, составе и влиянии на здоровье можно быстро найти и быть уверенным в их достоверности.
Например, вы ожидаете увидеть: Может содержать следы пшеницы. Или: Масса нетто: 1000 г.
Разумеется, вы не ожидаете, что среди этих сведений окажутся рецепты или рекламные заявления: это может быть буквально опасно.
Форма представления справочных сведений на пищевых продуктах настолько важна, что обычно регулируется законом. С такой же серьёзностью следует относиться ко всей справочной документации.