Як ви пишете документацію?

Всім привіт!

У нас на проекті існує велика кількість невеликих батчів (приблизно 150). І от уснує задача відобразити всі ці батчці на діаграмі, як вони взаємодіють і які ресурси використовують. Наразі ми використовуємо Visio, але:
— дуже часто всі забувають оновлювати діаграму
— коли багато елементів на схемі — пошук трохи ускаладнюється
— під Linux не так і зручно
— формат файлів бінарний — не можна переглядати зміни у VCS

А що ви використовуєте для документації?

👍ПодобаєтьсяСподобалось0
До обраногоВ обраному0
LinkedIn
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Загалом, crossplatform є декілька:

вже згаданий plantuml (plantuml.com) , та можна згадати непоганий blockdiag (blockdiag.com/en)

Я зазвичай це все обертаю в sphinx documentator (www.sphinx-doc.org) , тримаю або в окремому репозиторії (якщо проект складається з декількох), або суміщаю з поточним (як branch documentation). Чудово лягає в continious integration.

Виходить щось на зразок labs.voronenko.info/ProjectDocs ( результат компіляції і розгортання github.com/Voronenko/ProjectDocs )

Для написання документації беру приклад з javadoc, в коді ти не просто написав коментар, але описав і АРІ, функцію, метод та як все це працює, одночасно виходить і код і документація. Економить час.

Спробуй PlantUML — тулза ідеальна. На відміну від всяких онлайн-редакторів, які можуть в один момент обанкротитись і зникнути, твої діаграми можна буде прочитати і поредагувати завжди.

Також для нього є плагін в конфлюенс.

Вот это видео, с конфы GOTO; понравилось.
youtu.be/GM_J_jRp62g
Там и тулза есть, от этого автора.

Нынче только doxygen.
О, цікава штука. Дякую.

Поддерживаю.
Из плюсов (кроме бесплатности и выгрузки в XML) — есть бесплатный плагин для Confluence, можно редактировать диаграмму прямо на странице. Очень удобно

Коли доводилось вдаватись до діаграм, використовував www.visual-paradigm.com

Не пам’ятаю, який формат у файлів Visual Paradigm, але ось тут — plantuml.com — точно текстовий і буде більш-менш зручно переглядати зміни в VCS.

Здається був також експорт в xml

я бачу 2 мінуси :
— платний: навряд чи заапрувлять бюджет
— онлайн: нажаль ми повинні використовувати тіки тулзи встановлені всередині компанії

У нас в конфлюенсі є також Gliffy діаграми — але в останній версії, коли багато елементів — то висне (

1) так, окрім community версії, якщо вона ще є
2) те, чим я користувався, Visual Paradigm for UML, було кросплатформенним десктопним софтом (Java)

Підписатись на коментарі