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

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

Попробуем сформулировать слои документации

Черный ящик, оно же публичное API. Люди, которые им пользуются, не могут задать вопросы, не прониклись философией проекта и, в общем то, легко могут быть идиотами. Как правило в хорошем состоянии, потому что
- за это ебут
- ее читают
Инструкция по использованию. Если речь идет о сайте, тот тут должны быть как минимум описание админки, глоссарий сущностей и все прочее. Если проект поддерживается, то держать ее в актуальном состоянии не сложно — фидбек быстрый, канал связи налаженный. Если не поддерживается — ее тестируют во время приемки. Необходимость обсудим ниже
Инструкции для разработчиков. Сюда включается тезисы философии, пресловутый Code of Conduct, инструкции по разворачиванию тестового окружения и окружения разработки. Я работал в проектах где ее не было, если команда большая и нет огромной текучки кадров, то без нее вполне можно обойтись. Если проект опенсорсный и популярный, то обойтись нельзя
Служебный глоссарий. Опять же, как и в предыдущем пункте, штука опциональная
Служебные коментарии в стиле “это говно здесь для обратной совместимости, уберите когда она станет не нужна”. Или “ИзВеНиТе За нЕРовНый поЧерк”
Теоремы или доказательства корректности кода. Встречаются редко, в некоторых языках наоборот часто. В целом при наличии тестов опционально, подробности опять же ниже
Комментарии в стиле а как это работает. Полезность варьируется

Публичное API

Если ваш публичный API не документирован, вы либо еще не разрелизились, либо резко свернули не туда. Пары строк в ридми не достаточно.

Если вы пишете библиотеку — стоит воспользоваться системой документации в стиле yardoc, когда дока генерируется на основе вашего кода. Примеры использования обязательны везде. Не стоит забывать и про отдельное ридми с типовыми задачами.

Если речь идет про rest API или аналог с использованием других протоколов, она должна быть такой же, как и в случае с библиотекой. Типы параметров, возаращемого объекта, примеры использования. Не повторяйте ошибок большинства проектов, опишите типы в универсальном формате, который транслируется в типы вашего языка или хотя бы верифицируются в тестах. Не забывайте и про обзорный readme, обращайте внимание на то откуда брать парамеры для запросов. Итоговый результат должен многократно повторять одно и то же, задумайтесь о библиотеке для рендера посложнее чем просто компилятор markdown в html. Научите тестировщиков использовать postman для ручного тестирования.

В обоих случаях документация обязательно покрывается тестами. Даже если вы их обычно не пишете. Что покрывать? Примеры использования, разумется. Если вы можете автоматически сгенерировать тесты на большую часть документации — вы на очень правильном пути.

Инструкция по использованию

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

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

По поводу проектов без поддержки сказать ничего не могу.

Инструкция для разработчиков

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

Если речь про проекты с открытым исходным кодом, пусть там будет написана стандартная рыба и пусть она будет правдой. Предусмотрите какой-нибудь bin/setup и засуньте все туда. Если нужны зависимости которые не разруливаются вашей системой пакетов, напишите в ридми пример для ubuntu, у кого не убунта тот сам все поймет.

Служебный глоссарий

Если мы говорим об ООП или просто модульной архитектуре — любой непонятный термин должен быть классом или модулем. Документируйте его так чтобы было однозначно понятно. Если получилось нескромно мало текста — так и назовите сущность. Методы и функции лучше тоже однозначно понятно называть, хотя тут уже вступают в ход общепринятые соглашения для фреймворка / языка.

Служебные комментарии

Должно быть видно зачем оставили (HACK, FIXME, TODO), для кого, при каких обстоятельствах он станет не нужен.

Теоремы

Никто не пишет теоремы, если есть тесты. Имхо зря, если код действительно сложный стоит написать что b is not zero because it is difference between distinct elements of integer set перед тем как на него делить. Очень субьективно.

Комментари в стиле как это работает

Есть универсальный формат было => стало. Если это фунция, можно написать пример использования в принятой системе документации (а еще можно добавить типы, например). Если кусок функции - пишете прямо внутри и не парьтесь.

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