О документировании

В процессе разработки, поставки и сопровождения программного продукта обязательно прилагается сопутствующая документация или предоставляется доступ к актуальной информации:

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

При этом вышеуказанная информация должна всегда находиться в актуальном состоянии по поддерживаемым версиям продукта.

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

Документация Майкрософт

Прекрасный пример документации и учебных ресурсов Майкрософт для разработчиков и технических специалистов docs.microsoft.com. Можно также принимать участие в разработке документации согласно Руководству для участников.

В качестве внешнего сервиса можно использовать Read Docs - платформу для размещения документации по программному обеспечению в связке с сервисом GitHub - для хостинга IT-проектов и их совместной разработки.

Также широко используется публикация документации на GitHub Pages.

В качестве генераторов документации часто используются:

• MkDocs - скорее пакет Material для MkDocs для Python
• DocFX - инструмент для dotnet
• Sphinx -пакет Python

При этом в качестве редактора прекрасно подходит Visual Studio Code. Этот редактор при первом создании файла определенного типа сам и подскажет какие расширения можно установить для автоматической проверки синтаксиса и форматирования.