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

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

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

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

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

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

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

Учебник

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

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

Что нужно сделать

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

Чего не следует делать

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

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

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

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

Что нужно сделать

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

Чего не следует делать

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

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

Справочник

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

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

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

Объяснение

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

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