В каком формате писать документацию по программе?

Question

[Даниил]

Составляю не малую игру ( в частности на js, electron, потом возможен перенос на с++ qt)
Для начало работаю с описанием.
Написал огромную кучу блок-схем алгоритмов. И в процессе надо описать классы и структуры, а так же многие функции, расположения файлов в каталогах и т.д.
Вопрос. Если программа или формат какой-то, где удобно можно все описать. Типо Exel, а то в блокноте слишком много пробелов. Т.е. все что я напишу я потом вставлю как комментарии к самому коду. И вообще как правильно дифференцировать работу и разбить этапы НА ЭТАПЫ.

Answer 1

[Александр Глухов]

Я для себя пишу документацию в Markdown формате. На работе пишу в wiki.

Плюсы Markdown формата (спойлер: большее распространение)

1. Вы можете мини вики сделать из текстовых файлов при помощи: dynalon.github.io/mdwiki

2. Вы можете заливать Ваши статьи в Evernote

3. Гитлаб/хаб рендерит эти файлы автоматически.

4. Чистый текст и теги, файлы получаются легкими для хранения, передачи и редактирования.

Минусы:
1. Как ни крути нужно будет привыкать писать без WYSIWYG редактора. Потому, что так удобнее
2. Сначала очень много времени тратится на оформление, по мере привыкания время сокращается.

Стройте блок схемы там, где Вам удобно, я например предпочитаю Visio со студенческой скамьи. Потом экспортируйте в картинку, удобного Вам формата. Прикрепляйте к MD статье.

Answer 2

[xmoonlight]

1. Для Документирования JS-кода: documentation.js.org
2. Для блок-схем (включая погружение drill-down по клику в другие связанные схемы) https://www.edrawsoft.com/