✍️ Как написать отличную документацию: 2 впечатляющих примера с открытым исходным кодом

Хорошая документация экономит время, привлекает контрибьюторов и пользователей. Мы рассмотрим два open-source проекта с образцовой документацией, на которые стоит равняться каждому разработчику.

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

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

Преимущества хорошей документации многочисленны:

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

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

esbuild

esbuild – бесплатный сборщик и минификатор модулей с открытым исходным кодом для JavaScript.

README esbuild фокусируется исключительно на конечном пользователе инструмента. Сначала даются ссылки на основные разделы документации, такие как «Начало работы». Раздел «Почему?» кратко и с визуализацией объясняет, почему кто-то выберет эту библиотеку, а не другие решения. Перечислены возможности инструмента, что помогает определить, отвечает ли он потребностям пользователя. Также можно изучить FAQ, страницу «Начало работы», документацию по API и документацию по конкретной функции.

Архитектура документации esbuild

В каталоге docs находятся два файла: architecture.md и development.md. Документ начинается с оглавления и введения, объясняющего цель документа.

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

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

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

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

Журнал изменений esbuild

Подробная документация esbuild распространяется и на журнал изменений. Каждая запись содержит краткое описание, подробное объяснение и пример кода, показывающий вывод до и после изменения.

Качественная документация сыграла важную роль в росте популярности esbuild. На момент написания у проекта 37 000 звезд на GitHub, и он используется в 4.6 миллионах проектов.

Стань супермегаопытным программистом на курсах Proglib Academy со скидкой 35% до 1-го апреля!

• Математика для Data Science
• Базовые модели ML и приложения
• Алгоритмы и структуры данных
• Основы программирования на Python
• Основы IT для непрограммистов
• Frontend Basic: принцип работы современного веба

Redis

Redis – резидентная система управления базами данных класса NoSQL с открытым исходным кодом.

Введение и архитектура README-файла Redis

Раздел, представляющий Redis, краток, а остальная часть README предназначена для людей, вносящих вклад в кодовую базу Redis или читающих ее. Этот README ориентирован как на конечных пользователей, так и на контрибьюторов. Документация для обеих групп доступна, хотя и находится в разных местах.

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

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

Затем рассматриваются ключевые файлы и их структура.

Комментарии

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

Важно подчеркнуть, что длинные объяснения тривиальных строк кода не обязательны. Если операция проста и не требует дополнительного контекста для понимания, почему она написана именно так – лучше обойтись без комментария. Комментарий, который говорит то же самое, что и строка кода, излишен, если только строка кода не особенно сложна для чтения (в этом случае ее, вероятно, следует переписать) или цель не состоит в обучении.

Подведение итогов

• Тщательная документация экономит время не только для вас, но и для других.
  
• Некоторые проекты предназначены исключительно для развлечения или чего-то, над чем вы работаете в одиночку, и вы не уверены, вырастет ли проект в будущем. В таких ситуациях можно ничего не документировать.