День 2346. #BestPractices
Пишем Хорошую Документацию. Начало
Документация часто кажется второстепенной — рутиной, которую откладывают на конец спринта или вообще пропускают. Тем не менее, любой разработчик расскажет, что одно из его самых больших разочарований - продираться через плохую, устаревшую или отсутствующую документацию. Важно не просто иметь документацию, а создать такую, которую разработчики действительно ценят и используют. Это сигнализирует о том, что создатели заботятся о людях, использующих их ПО или API.

1. Знайте свою аудиторию (глубоко)
Прежде чем написать хоть слово, поймите, для кого вы пишете. Опытные или младшие разработчики? Внутренние команды, уже знакомые с экосистемой, или внешние пользователи, впервые сталкивающиеся с продуктом?
- Техническая компетентность: адаптируйте язык и глубину объяснения. Избегайте чрезмерно упрощённых объяснений для экспертов, но не предполагайте глубоких знаний предметной области от новичков.
- Цели: чего они пытаются достичь с помощью вашего ПО/API? Они ищут краткое руководство по началу работы, устранение конкретной ошибки, понимание расширенных концепций или интеграцию с другими системами? Структурируйте документы так, чтобы они отвечали этим конкретным потребностям.
- Контекст: где они обычно ищут информацию? Подойдёт ли интерактивный UI для API или лучше статические справочные страницы?
Поставьте себя на место разработчика. Какая информация вам нужна и как бы вы хотели, чтобы она была представлена?

2. Важна структура: создайте логическую основу
Даже самый точный контент бесполезен, если разработчики не могут его найти. Логическая структура обеспечивает ментальную карту, позволяя пользователям интуитивно ориентироваться.
- Чёткая иерархия: организуйте контент логически, начиная с вводных концепций (Начало работы, Установка) и переходя к конкретике (Справочник API, Руководства, Устранение неполадок). Используйте чёткие заголовки и подзаголовки (H1, H2, H3) последовательно.
- Оглавление: хорошо структурированное, всегда видимое (на боковой панели) оглавление позволяет пользователям видеть общую компоновку и быстро переходить к нужным разделам.
- Функциональность поиска: убедитесь, что поиск эффективно индексирует контент и выделяет ключевые слова в результатах. Разработчики часто знают, что им нужно, но не знают, где это находится.
- Перекрёстные ссылки: делайте ссылки на связанные концепции, руководства и API. Если вы упоминаете конечную точку API в руководстве, давайте прямую ссылку на неё. Это создаёт сеть знаний, а не изолированные хранилища.
- Информационная архитектура: планируйте поток. Рассмотрите возможность использования устоявшихся фреймворков, таких как Diátaxis (концепции, руководства, пояснения, справочные материалы), чтобы гарантировать, что вы систематически охватываете различные потребности в обучении.

3. Содержание: ясность, краткость и примеры
Основа документации — это содержание.
- Ясность: используйте понятный, недвусмысленный язык. Избегайте жаргона, где возможно, или чётко определите понятия при их первом использовании. Предпочитайте активный залог пассивному («Функция возвращает X» вместо «X возвращается функцией»).
- Краткость: разработчики заняты. Переходите к сути. Устраняйте бессмыслицу и ненужные слова. Используйте короткие предложения и абзацы. Маркеры и нумерованные списки отлично подходят для разбиения текста и выделения ключевой информации.
- Точность: неточная документация хуже, чем её отсутствие. Установите процессы проверки и обеспечьте обновление документов вместе с изменениями кода.
- Примеры кода: многочисленные, практичные, копируемые и вставляемые примеры, которые работают из коробки (включая необходимые импорты или настройки). Объясняйте, что делает код и почему он структурирован именно так. Покажите общие случаи использования, пограничные случаи и обработку ошибок. Если ваш API/SDK поддерживает несколько языков, предоставьте примеры на каждом из них.

Продолжение следует…

Источник: https://dev.to/therealmrmumba/beyond-code-how-to-create-beautiful-documentation-that-developers-actually-love-best-practices-hc4