Пишем немаленький проект. Растет число разработчиков, ролей, серверов, протоколов. Хочется иметь четкую, хорошо форматированную документацию, как, например, у Google : ) В чём, и как её лучше вести и генерировать html?
Ответ
Зависит от того, что именно вы хотите. Если вопрос об удобном формате для написания документации, то попробуйте 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-документацию, и заглушки для клиентской части под разные языки.
Комментариев нет:
Отправить комментарий