Комментарии 6
Мы вовсю используем его для генерации сайта с документацией, а вот для проектной документации пока дело не дошло. Все-таки, сложновато взаимодействовать со стейкхолдерами, которые ожидают ТЗ в формате «ворд».
Благодаря таким материалам хабр — торт.
Спасибо за отзыв. По поводу «ворд». Мне кажется — это правильный формат для стейкхолдеров. Word удобен для использования текста, для печати, для ревизии. Например, при написании статей для хабр я отработал следующий механизм. Пишу в Asciidoc, компилирую в Word или Open Document и отсылаю на ревизию. Далее компилирую в habr md-формат и публикую. Единственная ручная операция — копипаст получившегося md-файла.
Правда, тут хабр двигает новый формат, который с ошибками разбирает старый md-формат (возможно, они это подправят).
1. Её получается много… Очень много.
2. К такой документации относятся формально. И внутри могут быть косяки с таблицами, форматированием и их можно долго не замечать.
3. Как правило бесполезна, т.к. она абсолютно не последовательна и представляет собой не документацию, а всего лишь перекрестный справочник. Потому как в исходном коде обычно описывают синтаксис и параметры, но не семантику. Нет примеров использования и вообще описания общей картины, тем боле последовательного описания на разных уровнях детализации.
- Да, действительно, документации можно сгенерировать много, а можно по делу… При этом необходимо понимать, что мы, как правило, генерируем не документацию, а куски, которые инкапсулируем в общий проект документации. В этом и сила Asciidoc и аналогичных инструментов
- По поводу борьбы с косяками будет следующая статья
- См. первый пункт. Автоматическая генерация — это возможность, которую в некоторых случаях целесообразно использовать, не более того
PlantUML из коробки пол года как умеет визуализировать JSON, YAML, что помогает облегчить понимание и позволяет использовать в том числе и при составления проектной документации, описании использования, комментарии, например, вставляйте ваш JSON внутри
@startjson
@endjson
здесь www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
и для примера с доп.комментариями и описаниями забросьте:
@startjson
#highlight "transports" / "1" / "id"/ "0"
#highlight "sevice_groups" / "0" / "services" / "0"/ "transport"
#highlight "sevice_groups" / "0" / "services" / "1"/ "transport"
#highlight "sevice_groups" / "0" / "services" / "2"/ "transport"
#highlight "sevice_groups" / "0" / "services" / "3"/ "transport"
#highlight "sevice_groups" / "0" / "services" / "4"/ "transport"
{
"general": {
"autoLogByLogAddress": ["false","Функция вкл/выкл автологина (false/true)"],
"defaultUserName": ["user","Логин пользователя"],
"defaultDomainName": ["mail.ru","Домен пользователя"],
"defaultPassword": ["12345","Пароль пользователя"],
"loadFilesFromServer": {
"use": ["false","Функция вкл/выкл загрузки файлов с сервера(false/true)"],
"timeout": 10000
}
},
"transports": [
{
"type": "tcp",
"id": "local_tcp",
"uri": "127.0.0.1",
"timeout": 30000,
"keepAlive": false,
"ssl": {
"use": false,
"cert_file_path": "*.crt",
"key_file_path": "*.key",
"ca_file_path": "*.crt"
}
},
{
"type": "jms",
"id": ["service","Подключение к группе сервисов - которые указаны в поле <color:blue>\"transport\",\\n которое находится в объекте \"Настройки сервисы\""],
"uri": ["failover:(tcp://IP-адрес:12345?transport.trace=false&transport.wait=60000)","Подключение к серверу"],
"timeout": 60000
}
],
"sevice_groups": [
{
"title": "Настройки сервисы",
"services": [
{
"type": "access",
"id": "access1",
"transport": "service",
"endpoint": "ACCESS",
"title": "Access title for manager"
},
{
"type": "archive",
"id": "archive1",
"transport": "service",
"endpoint": "ARCHIVE",
"title": "Archive title for manager"
},
{
"type": "doc",
"id": "doc1",
"transport": "service",
"endpoint": "DOC",
"title": "Doc title for manager"
},
{
"type": "report",
"id": "report1",
"transport": "service",
"endpoint": "REPORT",
"title": "Report title for manager"
}
]
}
]
}
@endjson
Спасибо, очень хороший пример. Чтобы упросить чтение читателям вашего комментария, сразу приведу картинку (использовал kroki). Также держим в уме, что самостоятельно сделать шаблон для генерации аналогичной картинки (например, если есть специфические требования к отображению в конкретном документе) — это несколько десятков строчек достаточно простого кода.
Автоматическая генерация технической документации