Jul 14 2012 at 11:15

Easydoc — Agile документация

Invite pending

Эта статья рассказывает о новом интересном подходе к написанию технической документации и о его реализации — инструменте под названием Easydoc.

Нужна документация

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

В кабинет заходит гендиректор:

— Парни, отличная новость! У нас новый потенциальный клиент: UncleSam Inc. Очень большая компания с очень большими деньгами. Но у них есть одно важное требование: чтобы нам с ними заинтегрироваться, у нас должна быть хотя бы минимальная техническая документация по каждому из модулей. А у нас сейчас документации вообще никакой! Надо её срочно сделать.

Варианты ответа:

«Окей, в следующем спринте может сделаем.»
«Так это техписатель должен делать, а я программист.»
«А что именно документировать? API? Конфиги?»
«А кто её поддерживать будет?»

И так далее. И все эти ответы правильные. Но техписателя нанять нет возможности, а сроки поджимают. Не хочется потерять контракт с UncleSam.

Что же делать?

Easydoc, о котором в этой статье пойдёт речь, отвечает на этот вопрос так:

Простейшую техническую документацию могут написать программисты.
Эта документация должна находится в исходниках.

— Прям в исходниках?

— Ну да.

— Как в JavaDoc?

— Ну почти.

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

Документация всегда синхронизирована с кодом (правим код, правим и документацию, которая рядом).
Экономит время. Не нужно переключаться на Wiki, находить нужный раздел, вспоминать синтаксис… (Кто помнит наизусть синтаксис MediaWiki?) Просто пишешь доку там же, где пишешь код.
Код становится гораздо лучше документированным (читаешь код — тут же и документация).
Документацию теперь можно включать в Code Review.

Как это делается

Итак, документацию мы пишем внутри исходных файлов, в комментариях. Почти как в JavaDoc или ASDoc. Только в случае JavaDoc документация привязана к методам и классам. Easydoc идёт дальше, и с помощью него мы можем задокументировать любой участок кода с интересующим нас функционалом. Достаточно внутрь комментария включить специальные тэги: @@easydoc-start@@ и @@easydoc-end@@. Текст, который находится между ними (по умолчанию HTML, также поддерживается Markdown), будет помещён в итоговый HTML-файл с документацией. Этот HTML-файл Easydoc сгенерирует, пройдясь по нашим исходным файлам.

Вот пример:

/*@@easydoc-start@@
<h1>RESTful API</h1>

Сервис предоставляет RESTful API для доступа к управляемым ресурсам.
Методы API доступны по URL http://company.com/myservice/api
@@easydoc-end@@*/
@Controller("/api")
class RESTController {
    ...
}

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

Доки могут находиться и в конфигурационных файлах. И вообще, в любых текстовых файлах. Например, в XML:

<beans>
...

<!--@@easydoc-start@@
<h1>База данных</h1>

Сервис использует базу данных, конфигурация которой находится в файле database.xml. 
@@easydoc-end@@-->
<import location="database.xml"/>
...
</beans>

… или .properties:

#@@easydoc-start, ignore=#@@
#
# <h1>Конфигурация</h1>
#
# Приложение конфигурируется с помощью файла application.properties.
#
#@@easydoc-end@@

app.greeting=Hello World!

Доки можно компоновать, задавая вложенность одних доков в другие, можно управлять порядком, стилем и ещё очень много чем. Но для того, чтобы начать, достаточно просто написать несколько примитивных доков и запустить Easydoc.

Запустить? А как?

Проще всего использовать Easydoc как Maven-плагин. Для этого нужно в pom.xml в секции

 прописать следующее:




<plugin>
    <groupId>com.github.weekens</groupId>
    <artifactId>easydoc-maven-plugin</artifactId>
    <version>0.4.17</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>


После этого Easydoc будет запускаться автоматически при каждой сборке, сканируя всё, что у Вас в src/ (+ файл pom.xml) и генерируя результирующий HTML в target/easydoc.



А если я не использую Maven?


Тогда можно из-под командной строки.



java -jar easydoc.jar


Ещё планируется реализовать Ant-овский плагин.



Где все эти тайные знания?


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



И что, это правда работает?


Да, это решение уже работает как минимум в одной компании. И это только начало! Ещё нужно много чего допилить/додумать/реализовать. Например, интерфейс командной строки, возможно, пока не столь удобен. Также, в планах множество фич, например, генерация многостраничной документации и разбиение доков на профили (для программистов, пользователей, админов, менеджеров и т.д.).



Всё это будет сделано. Главное, коллеги, чтобы вы этим пользовались. Если вы находите такой подход к документированию интересным и работоспособным - скачивайте Easydoc, пишите доки, создавайте баги в трекере, форкайте проект на Github. Вместе мы можем сделать так, чтобы это действительно хорошо работало!

Tags:

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

Hubs:

Lumber room