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

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

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

Мы следуем фреймворку документации Diátaxis Daniele Procida.

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

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

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

Учебник

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

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

Что делать

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

Что не делать

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

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

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

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

Что делать

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

Что не делать

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

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

Справочник

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

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

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

Объяснение

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

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