Як ви пишете документацію?
Всім привіт!
У нас на проекті існує велика кількість невеликих батчів (приблизно 150). І от уснує задача відобразити всі ці батчці на діаграмі, як вони взаємодіють і які ресурси використовують. Наразі ми використовуємо Visio, але:
— дуже часто всі забувають оновлювати діаграму
— коли багато елементів на схемі — пошук трохи ускаладнюється
— під Linux не так і зручно
— формат файлів бінарний — не можна переглядати зміни у VCS
А що ви використовуєте для документації?
14 коментарів
Додати коментар Підписатись на коментаріВідписатись від коментарівЗагалом, 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; понравилось.
Там и тулза есть, от этого автора.
draw.io
xml
Поддерживаю.
Из плюсов (кроме бесплатности и выгрузки в XML) — есть бесплатный плагин для Confluence, можно редактировать диаграмму прямо на странице. Очень удобно
Коли доводилось вдаватись до діаграм, використовував www.visual-paradigm.com
Не пам’ятаю, який формат у файлів Visual Paradigm, але ось тут — plantuml.com — точно текстовий і буде більш-менш зручно переглядати зміни в VCS.
Здається був також експорт в xml
я бачу 2 мінуси :
— платний: навряд чи заапрувлять бюджет
— онлайн: нажаль ми повинні використовувати тіки тулзи встановлені всередині компанії
У нас в конфлюенсі є також Gliffy діаграми — але в останній версії, коли багато елементів — то висне (
1) так, окрім community версії, якщо вона ще є
2) те, чим я користувався, Visual Paradigm for UML, було кросплатформенним десктопним софтом (Java)