Pull to refresh

Comments 6

Отличная статья про asciidoc.
Мы вовсю используем его для генерации сайта с документацией, а вот для проектной документации пока дело не дошло. Все-таки, сложновато взаимодействовать со стейкхолдерами, которые ожидают ТЗ в формате «ворд».

Благодаря таким материалам хабр — торт.

Спасибо за отзыв. По поводу «ворд». Мне кажется — это правильный формат для стейкхолдеров. Word удобен для использования текста, для печати, для ревизии. Например, при написании статей для хабр я отработал следующий механизм. Пишу в Asciidoc, компилирую в Word или Open Document и отсылаю на ревизию. Далее компилирую в habr md-формат и публикую. Единственная ручная операция — копипаст получившегося md-файла.


Правда, тут хабр двигает новый формат, который с ошибками разбирает старый md-формат (возможно, они это подправят).

Сколько видел автоматически сгенерированной документации.
1. Её получается много… Очень много.
2. К такой документации относятся формально. И внутри могут быть косяки с таблицами, форматированием и их можно долго не замечать.
3. Как правило бесполезна, т.к. она абсолютно не последовательна и представляет собой не документацию, а всего лишь перекрестный справочник. Потому как в исходном коде обычно описывают синтаксис и параметры, но не семантику. Нет примеров использования и вообще описания общей картины, тем боле последовательного описания на разных уровнях детализации.
  1. Да, действительно, документации можно сгенерировать много, а можно по делу… При этом необходимо понимать, что мы, как правило, генерируем не документацию, а куски, которые инкапсулируем в общий проект документации. В этом и сила Asciidoc и аналогичных инструментов
  2. По поводу борьбы с косяками будет следующая статья
  3. См. первый пункт. Автоматическая генерация — это возможность, которую в некоторых случаях целесообразно использовать, не более того

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). Также держим в уме, что самостоятельно сделать шаблон для генерации аналогичной картинки (например, если есть специфические требования к отображению в конкретном документе) — это несколько десятков строчек достаточно простого кода.
image

Only those users with full accounts are able to leave comments. Log in, please.