Какой инструмент документирования подойдет?

Question

[Vitaliy]

Какой бесплатный инструмент подойдет для документирования проекта с серверной частью на j2ee + mysql +neo4j, и клиентской на C++? Важно, чтобы это все было автоматизировано как для первой, так и второй стороны (чтобы не путаться с различными описаниями комментариев и выполнять минимум рутиной работы).
Вроде бы о Doxygen много положительных статей, но действительно ли он так хорош? Или есть какие-то недостатки?

Answer 1

[Эдуард Тибет]

Традиционно со своей стороны я посоветую сначала ответить (максимально полно) на следующие уточняющие вопросы (доступны по ссылкам):

Начать отсюда: Где посмотреть примеры документирования разработки сайта?
Затем обязательно вот это: Как документировать существующее решение?
И, наконец, вот это: Где лучше всего вести документацию по сервису?

Comments

[Vitaliy]

ДЛЯ ЧЕГО вам надо писать документацию?
- чтобы легче вспоминать что и где есть из функционала, как мне, так и тем, кто подключится к проекту
1. Предполагается ли документацию выносить наружу?
- нет
2. В каких выходных форматах вы хотите поставлять документацию? Предполагается ли печатка (как класс)?
- pdf
3. Предполагается ли многоуровневая документация (т.е., например, несколько модулей для клиента А, несколько для клиента Б и т.п.)?
- не решено
4. Надо ли документировать API (руками или автоматически)?
- да, руками по своим методам
5. Кто будет осуществлять поддержку всего этого хозяйства?
- сам разработчик
6. Какой объем (примерно) сейчас и какой объем будет после года?
- неизвестно
7. Надо ли хранить версионность всего этого добра?
- нет

[Эдуард Тибет]

Виталий Столяров: п.2 противоречит п. 1, а также пункту "для чего". Печатка нужна только для распространения наружу. Вы не будете печатать у себя + искать внутри. Вам нужен только html c поддержкой поиска.
п.7 - вы уверены в том, что вам не нужно будет держать версионность? Т.е. вопрос коллеги типа "а как там у нас это было реализовано в предыдущей останется без ответа" (точнее, без ответа из документации).

[Эдуард Тибет]

Виталий Столяров: И еще... как я понимаю, нужен только API и все? Т.е. никаких руководств, архитектурных решений и т.п. (т.е. "нормальных документов") не нужно.

[Vitaliy]

Эдуард Тибет: пока неизвестно, время покажет что к чему, поэтому я и задал вопрос, так как ранее не работал над крупными проектами

[Эдуард Тибет]

Виталий Столяров: Так вы сначала определитесь, нужен только API или нет? :) Т.к. разница очень большая. Если вам нужен только API, то вам будет достаточно:
- генератора комментариев из кода.
- что-то типа Swagger (для REST API). Здесь еще существуют другие нотации и инструментарий - RAML и WADL (последний основан на xml, первые два на json + yaml в качестве "человекочитаемого" варианта).
- web сервер для отображения всего добра.
- скрипты генерации (проще самописные, т.к. вариантивность маленькая).

ОДНАКО, если вам надо делать нормальную документацию: ТЗ, архитектурные документы, руководства администратора, white papers и т.п. (т.е. то, что создается человеком, как документ, содержит иллюстрации и т.п.), то инструментарием выше вам не обойтись.
Вам придется добавлять:
- SCM (обязательно)
- Authoring tools (чтобы писать)
- generation tools + CI (чтобы все генерилось без участия человека).

Если вероятность расширения продукта велика и вынос наружу будет (а это только вам решать), то следующие элементы в структуре must have:
- SCM
- Authoring tools
- CI

Лично я занимаюсь сложными системами, и, конечно, мог бы вам посоветовать использовать много чего, но все-таки вопросы цены внедрения/сопровождения имеет немаловажное значение. Не зря я вам посоветовал посмотреть Где лучше всего вести документацию по сервису? - это напрямую относится к деньгам при выборе решения.

[Vitaliy]

Эдуард Тибет: не только API, его же нужно отдельно для сторонних разработчиков, а мне не требуется ничего замысловатого для документирования всего исходника приложения, нужно лишь сопровождать код документацией, по которой будет легче вспомнить что там есть. Хотя есть такой вариант, чтобы документировать только в UML, вот и важно то, чтобы иметь это в удобочитаемом виде с поиском и т.д.

[Эдуард Тибет]

Виталий Столяров: Виталий, по вашему ответу я уверен, вам надо основательно подумать над моими изначальными вопросами, осознать их и ответить на них. Даже, если это займет несколько дней. На текущий момент я вижу - вы смешиваете все в кучу. Т.е. вы просите подсказать вам решение конкретной проблемы, но не можете сформулировать четко эту проблему(-ы) - например, у вам по ходу диалога появляются все новые и новые требования.

[Vitaliy]

Эдуард Тибет: единственный вопрос остается в силе это "Какой инструмент документирования подойдет?"

[Эдуард Тибет]

Виталий Столяров: Так в том то и дело. По требованиям выбираются инструменты и процессы, а не наоборот. Вы, конечно, можете попробовать от обратного, но это будет, мягко скажем, неоптимально :)

[Vitaliy]

Эдуард Тибет: кажется, требования я излагал выше, это сопровождение написанного кода документацией, автоматически сгенерированной из комментариев к соответствующему коду

[Эдуард Тибет]

Виталий Столяров: Вы противоречите сами себе. Приведу цитаты:
- "сопровождение написанного кода документацией, автоматически сгенерированной из комментариев к соответствующему коду"

однако с другой стороны вы отвечаете на вопрос:

- "Надо ли хранить версионность всего этого добра - нет".

Сопровождение НЕ может быть без SCM. Это принципиально.

Давайте я объясню вам, в чем вы неправы. Вы хотите получить "что-то" и "прямо сейчас", "не задумываясь о требованиях". Я же, со своей стороны, даю советы "как надо", а не "как хочется". Безусловно, на тостере много людей, которые практически всегда отвечают не задумывась "Я использую X, попробуй", "Слышал, что Y подходит". Если вас удовлетворят такие ответы без уточняющих вопросов - без проблем - думаю вам здесь подскажут.

P.S. И, кстати, общее решение, я уже вам привел "Если вам нужен только API, то вам будет достаточно:...." - Какой инструмент документирования подойдет?

[Vitaliy]

Эдуард Тибет: допустим, будет использоваться SCM, что тогда?

[Эдуард Тибет]

Виталий Столяров: Тогда вам надо:
1. Определить, что конкретно вы будете документировать.
2. Надо ли вам выцеплять это автоматически.
3. Попробовать несколько инструментов в виде теста. Про doxygen вы уже знаете. Можете еще попробовать Sphinx. Или еще погуглить. Для REST - я приводил инструменты ранее.