Где разместить код документации?

В настоящее время я использую две системы для написания документации кода (я использую C ++):

• Документация о методах и членах класса добавляется рядом с кодом в формате Doxygen. На сервере Doxygen запускается на источниках, поэтому вывод можно увидеть в веб-браузере
• Страницы обзора (описывающие набор классов, структуру приложения, пример кода, ...) добавляются в вики

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

Мой коллега теперь предлагает поместить все в Doxygen, потому что тогда мы можем создать один большой файл справки со всем в нем (используя либо Microsoft WorkShop HTML, либо Qt Assistant). Меня беспокоит то, что редактирование документации в стиле Doxygen намного сложнее (по сравнению с Wiki), особенно когда вы хотите добавить таблицы, изображения, ... (или есть инструмент предварительного просмотра для Doxygen, который не требует генерации код, прежде чем вы можете увидеть результат?)

Что используют большие проекты с открытым исходным кодом (или с закрытым исходным кодом) для написания своей документации кода? Они также делят это между Doxygen-style и Wiki? Или они используют другую систему?

Каков наиболее подходящий способ выставить документацию? Через веб-сервер / браузер или через большой (несколько 100 МБ) файл справки?

Какой подход вы используете при написании документации кода?

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

С другой стороны, вы должны подумать о том, перевешивают ли эти преимущества легкость вашей вики. Круг редактирования / создания / уточнения редактирования / создания снова может быть быстрее с вашей вики. Я предполагаю, что вы можете сделать этот цикл достаточно быстрым, если doxygen сохранит ваши обзорные страницы в качестве отдельного подпроекта doxygen. Вы можете использовать внешние возможности связывания doxygen, что, разумеется, не является заменой «быстрого предварительного просмотра», но является шагом в этом направлении. Пока я этого не делал сам, но, думаю, вы должны попробовать это сами, если хотите знать, работает ли это в вашем случае.

Что касается других проектов: я думаю, что такой инструмент, как doxygen, предназначен в первую очередь для документации библиотеки. Если вы не являетесь сторонним поставщиком библиотек и каждый, кто использует ваши библиотеки, имеет полный доступ к исходному коду, то необходимость в таком инструменте, как doxygen, вызывает сомнения. В нашей команде, например, у нас почти нет внешних документов вне кода, кроме документов конечных пользователей и документов наших моделей баз данных. Наши основные инструменты для такой документации DocBook и фат , что дает нам удовлетворительные результаты.

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

Я знаю, что это будет трудно поддерживать.

Практический ответ:

На практике первое, что делают разработчики, это проверяют код.

Как разработчик, мне нравится иметь внешнюю документацию, такую ​​как Wiki, руководства. Но, первое, что я делаю, это проверяю код (иногда от других разработчиков, иногда от меня).

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

Иногда руководители проектов и другие руководители не заботятся о документации, а другие разработчики - нет.

И самое лучшее, что я могу сделать, это добавить некоторые комментарии к коду.

Удачи

Некоторые используют другие системы - взгляните на Sphinx в Python, например, у них есть система документов все-в-одном, которая строит все (это также работает для C / C ++)

Я всегда считаю документацию отдельной от кода, doxygen - это здорово, но он предназначен для обзора API, а не для «документации». Для этого хороша вики, но я предпочитаю использовать ASCIIDOC и хранить результаты этого в контроле исходного кода вместе с кодом, главным образом потому, что я могу генерировать PDF-файлы из них для передачи другим людям (например, тестировщикам, клиентам и т. Д.)

Doxygen позволяет создавать PDF, HTML, вики-страницы, практически все, что вы можете придумать.

Мое личное предпочтение - иметь и Doxygen, и вики, и скрипт, или что-то, что можно проверить, когда они расходятся.

Начиная с версии 1.8.0 doxygen поддерживает Markdown , что должно сделать написание статических страниц таким же удобным, как в вики-системе.

Целевая аудитория

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

• Как разработчик: документация, связанная с изучаемым кодом, подробности, такие как контракт интерфейса и примеры использования. Возможно некоторая документация высокого уровня, и спецификации протокола для хорошей меры.
• Как пользователь: документация, доступная через меню справки или доступный веб-сайт о том, как использовать программное обеспечение.
• Для бизнес-аналитика полезна документация, доступная в виде документов или доступного веб-сайта. Скромное количество деталей о протоколах, высокоуровневой архитектуре и вариантах использования являются лучшими.

техническое обслуживание

От того, где разместить источник этой документации, будет зависеть ваша аудитория и кто пишет для вашей аудитории.

• Есть только дом разработчиков? Поместите все в код. Это будет способствовать его обновлению. Вам нужно будет работать над культурой, которая поощряет обновления документации так же важно, как и изменения кода.
• Есть дом разработчиков и авторов документации? Разделите обязанности. Используйте ориентированные на разработчика инструменты для разработчиков, используйте инструменты авторов документации для авторов документации.

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

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

Интеграция документации

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

Бизнес-аналитик вполне доволен спецификациями API, Designs Specs и сценариями использования, которые размещаются в отдельных документах или отдельных разделах веб-сайта.

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

Ваш случай

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

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

• Инструменты исходной документации (например, doxygen) могут создавать html, и вики живет на веб-сервере. Это была бы простая точка интеграции, чтобы просто обслуживать встроенную версию вместе с вики и связывать их.
• Некоторые вики-продукты позволяют вам запускать вики прямо из файла, который вы можете зарегистрировать в базе кода. Это дает простой инструмент wysiwyg, сохраняя документацию в паре с кодом.
• Другие форматы, такие как pdf, также могут быть адаптированы, но это зависит от конкретного инструмента, который вы хотите использовать. Возможно, имеет смысл собрать вашу вики в файлы уценки и передать их через doxygen (или другие инструменты). Возможно, имеет смысл отдельно отразить вики и исходный код PDF и использовать инструмент слияния PDF.

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

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

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