Написание документации

Документация Wagtail написана в четырёх режимах передачи информации. Каждый тип передачи информации имеет цель и ориентирован на определённую аудиторию.

• Учебник, ориентированный на обучение
• Руководство по выполнению, ориентированный на достижение цели
• Справочник, ориентированный на информацию
• Объяснение, ориентированный на понимание

Мы следуем документоведческой системе Diátaxis Даниэля Проциды.

Выбор режима написания

Каждая страница документации Wagtail должна быть написана в единственном режиме передачи информации. Страницы со смешанными режимами сложнее понять. Если у вас есть документы, которые смешивают типы передачи информации, лучше разделить их. Добавляйте ссылки на первый раздел каждого документа для перекрестной ссылки на другие документы по той же теме.

Написание документации в определённом режиме поможет нашим пользователям понять и быстро найти то, что они ищут.

Учебник

Учебники разработаны как обучающие ресурсы, которые ведут новичков по определённой теме. Для эффективного обучения учебники должны содержать примеры, иллюстрирующие рассматриваемые темы.

Учебники необязательно следуют лучшим практикам. Они разработаны, чтобы облегчить начало работы. Учебник должен быть конкретным и повторяемым. Он должен внушать уверенность и приводить к успеху каждого учащегося каждый раз.

Рекомендации

• Используйте разговорный язык
• Используйте сокращения, говорите от первого лица множественного числа, будьте успокаивающими. Например: «Мы собираемся сделать это»
• Используйте изображения или конкретные результаты кода, чтобы убедить людей в том, что они на правильном пути. Например: «Ваша новая страница входа должна выглядеть так» или «В вашем каталоге теперь должно быть три файла».

Не следует

• Не говорите людям, что они собираются изучить. Вместо этого говорите им, какие задачи они будут выполнять.
• Не используйте опциональность в учебнике. Слово «если» — это признак опасности! Например: «Если вы хотите сделать это…» Ожидаемые действия и результаты должны быть однозначными.
• Не предполагайте, что обучающиеся имеют предварительные знания по теме.

Подробнее об учебниках

Руководство по выполнению

Руководство предлагает советы о том, как лучше всего выполнить задачу. Руководства по выполнению заданий ориентированы на задачу с чёткой целью или задачей.

Рекомендации

• Дайте руководству хорошее имя — убедитесь, что обучаемый понимает, что именно делает руководство.
• Фокусируйтесь на действиях и результатах. Например: «Если вы сделаете X, то произойдёт Y»
• Предполагайте, что обучаемый имеет базовое понимание общих концепций
• Укажите читателю дополнительные ресурсы

Не следует

• Не используйте излишне строгий тон. Например: «Вы абсолютно не должны делать X»

Подробнее о руководствах по выполнению

Справочник

Справочная информация ориентирована на информацию. Справочник хорошо структурирован и позволяет читателю найти информацию по определённой теме. Они должны быть короткими и по существу. Превосходно, если они будут скучными! Используйте повествовательное наклонение. Например: «Унаследуйте от модели Page»

Большинство справочных материалов будут автоматически генерироваться на основе doc-строк в коде Python.

Подробнее о справочнике

Объяснение

Объяснения ориентированы на понимание. Они высокого уровня и предоставляют контекст для концепций и решений дизайна. В объяснениях мало или совсем нет кода, которые используются для углубления теоретического понимания практического черновика. Объяснения используются для установления связей и могут потребовать определённых предварительных знаний о принципах, которые исследуются.

Подробнее об объяснении