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