По мере развития технологий и оптимизации рабочих процессов некоторые из них обратились к автоматизированным инструментам, таким как Doxygen , Sphinx , Swagger и т. д ., для автоматического создания технической документации.
Каковы наиболее очевидные ограничения этих инструментов и как их можно устранить, чтобы сэкономить время тем, кто занимается документированием?
Doxygen и т. д. на самом деле не генерируют документацию автоматически. Они реструктурируют и форматируют информацию, написанную от руки либо в виде кода (который является формой структурированных данных), либо в виде комментариев, записанных в коде. Они форматируют и публикуют информацию автоматически. Они не генерируют контент автоматически.
Для меня самым очевидным ограничением этих инструментов является то, что они представляют собой отдельную цепочку инструментов публикации, не связанную с цепочкой инструментов, используемой для остального набора документации. Это означает, во-первых, что вам придется дважды выполнять всю работу по настройке и поддержке цепочки инструментов, представления и форматирования вашего контента. И поскольку все они имеют относительно грубые механизмы публикации, вы часто не можете добиться, чтобы их выходные данные соответствовали дизайну остального набора документации.
Вторая проблема заключается в том, что это означает отсутствие интеграции между контентом, который они производят, и остальным вашим контентом. В бумажные дни это не вызывало особого беспокойства, но теперь, когда мы публикуем информацию в основном в Интернете, стало сложнее выполнять элементарные действия, такие как создание ссылок из упоминаний функции в руководстве программиста на листинг этой функции в ссылка на API.
Решение этих проблем состоит в том, чтобы взять выходные данные XML из этих инструментов и передать их в общую цепочку инструментов. Конечно, это предполагает, что ваша общая цепочка инструментов основана на XML или, по крайней мере, способна получать и интегрировать поток XML. Это не относится к большинству готовых инструментов для написания и публикации. В результате ваши документы API остаются на острове.
Автоматизированные системы, такие как Sandcastle и Swagger, хорошо преобразовывают синтаксис кода в документацию. Те будут производить маргинальную документацию. Чего они не делают, так это добавляют понимание звонков. Метод редко существует сам по себе. Всегда необходимы дополнительные примечания, разъяснения предостережений, побочные эффекты, разъяснения для каждого параметра, возвращаемых значений, самого метода и даже использования метода в более широком контексте. Сравните, например, типичную справочную страницу MSDN с любой справочной страницей REST. Для каждого метода страница MSDN длиннее и подробнее, как того хотят разработчики материалов. ОТДЫХА, как правило, мало, с меньшим количеством дополнительных примечаний.
Затем есть примеры и фрагменты кода. Ни одно автоматически сгенерированное приложение не может сделать это. Многие люди не понимают документацию по API. В 95% случаев разработчики просто хотят скопировать и вставить образец. Автоматизированная документация редко их генерирует.
Многие думают, что достаточно использовать справочную страницу. Это не. Важна простота и полнота ответов на вопросы. В этом разница между адекватной документацией и отличной документацией.
Адам Майкл Вуд
EJoshuaS - Поддержи Украину