В чем вести / генерировать тех. документацию API растущего проекта?

#документация #api #проектирование

Пишем немаленький проект. Растет число разработчиков, ролей, серверов, протоколов.
Хочется иметь четкую, хорошо форматированную документацию, как, например, у Google : )
В чём, и как её лучше вести и генерировать html?     

Ответы

Ответ 1

Зависит от того, что именно вы хотите.
Если вопрос об удобном формате для написания документации, то попробуйте AsciiDoc/AsciiDoctor.
Это plain-text формат, напоминающий Markdown и вики-разметку. Он позволяет отделить
текст документации от шаблона оформления (приятные шаблоны "из коробки") и умеет собираться
и в HTML, и в PDF, и в DocBook, и по всякому. Активно развивается инфраструктура вокруг
него. Его удобно хранить в контроле версий (это plain-text формат, который легко диффать
и мержить) и работать с ним как с исходным кодом документации.
Если вопрос о готовой системе хранения документации и совместной работы - посмотрите
Atlassian Confluence: довольно приятная штука, много плагинов, интегрируется как с
инфраструктурой Atlassian (багтерекер JIRA, билдсервер Bamboo, и т.п.) так и с популярными
тулами вроде Balsamiq Mockups.
Еще доводилось пользоваться для этой цели MediaWiki, но у нее, как мне кажется, порог
вхождения выше.
Если речь об автоматизации документирования всяких REST API, то я не так давно в
ходе поисков нашел отличную вещь - Swagger. Этот проект представляет собой попытку
стандартизировать описание REST службы в виде набора xml/json-документов, на основе
которых можно сгенерить как "живую" online (с возможностью подергать сервисы прямо
со страницы) так и обычную offline-документацию, и заглушки для клиентской части под
разные языки.


Ответ 2

Пишу документацию/справочник по разрабатываемой системе.
Тоже озадачился, на чем это делать.
Нашел интересную вещь Outwiker
http://jenyay.net/Soft/Outwiker