Как писать техническую документацию к софту?

Question

[iMisterio]

Добры день, знатоки!

Проблема
Имеется написанная программа. Необходимо написать для нее техническую документацию. Т.к проект завершен, и на случай если через некоторое время он будет возобновлен, не пришлось изучать код как в первый раз.

Вопросы:

1. Есть какие-то методологии по написанию документации?
   
2. Есть какие-то удобные (платные, бурж) SAAS-сервисы для упрощения ведения документации?
   
3. Не нашел особо много информации, по написанию документации, подскажите запросы, по которым смогу "нарыть" больше инфы по этому вопросу, или ткните на конкретные ресурсы/статьи?
   
4. Как называется профессия людей, кто занимается только написанием документации?
   
5. Сколько стоит в среднем работа людей пишущих документацию?
   

Спасибо.

Answer 1

[DISaccount]

А вот, пожалуйста. Натравливаем на исходники и заполняем пробелы в описании/комментариях.

Answer 2

[Алексей]

Как называется профессия людей, кто занимается только написанием документации?

Профессия называется Технический писатель. Могу предложить начать со ссылок в конце статьи на wikipedia.

Answer 3

[Тимур]

Можно вспомнить курсовой по программированию.

Как было у нас в учебном заведении, документация делится на 2 части.
1. Общая
2. Специальная

Общая часть - описывается используемое ПО для разработки продукта.

Спецаильная часть - описываются, все участки программы. Макро блок-схема, Блок-схемы проблемных участков. Листинг программы. Описание каждой функции, ее типы и т.д. и т.п. ER-диаграмма, связь таблиц БД. Сколько полей в таблице, описывается каждое поле таблицы, его тип и т.д и т.п

Возможно стандарты разные.

Answer 4

[MonkAlex]

Главный вопрос - размер проекта.
Если там до 3 тысяч строк, то будет достаточно хороших xml комментариев к классам и методам.

Если кода много, то как минимум нужна архитектура (кто от кого зависит, кто за что отвечает и т.д.) , плюс мне всегда помогают тесты, если они есть.

Answer 5

[Станислав Салангин]

Есть какие-то методологии по написанию документации?
Да. В Вашем случае можно писать по ГОСТ 19. Если проект большой, то по ГОСТ 34. Есть стандарты ISO

Есть какие-то удобные (платные, бурж) SAAS-сервисы для упрощения ведения документации?
Например, в WIki можно ее хранить.

Не нашел особо много информации, по написанию документации, подскажите запросы, по которым смогу "нарыть" больше инфы по этому вопросу, или ткните на конкретные ресурсы/статьи?
В вашем случае это: техническая документация, описание API, описание БД, Javadoc, Doxygen

Как называется профессия людей, кто занимается только написанием документации?
Техписатели, techwriter-ы, разработчики документации.

Сколько стоит в среднем работа людей пишущих документацию?
Оклад техрайтера сильно зависит от квалификации, от языка, на которм он пишет, а также от сложности проекта и типа документации. Можно сказать, что от 30 до 100 тысяч в месяц.

Answer 6

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

Есть какие-то методологии по написанию документации?

Для госзаказчиков - ГОСТ (19, 34). В обычной практике - ISO, "упрощенный гост" и т.п.

Есть какие-то удобные (платные, бурж) SAAS-сервисы для упрощения ведения документации?

Написания в смысле "руками" или "отдачи" (generation)?

Не нашел особо много информации, по написанию документации, подскажите запросы, по которым смогу "нарыть" больше инфы по этому вопросу, или ткните на конкретные ресурсы/статьи?

Вы лучше сформулируйте, что вам надо. Ответить будет проще. Например, сначала прочитайте вот эти посты:

https://toster.ru/answer?answer_id=658763
https://toster.ru/answer?answer_id=658771

и конкретизируйте вашу задачу.

Как называется профессия людей, кто занимается только написанием документации?

Согласен с предыдущим участником.

Сколько стоит в среднем работа людей пишущих документацию?

Все зависит от вариантов: регион? в штате/не в штате? объем? язык создания документов? навыки?

Answer 7

[semenovsanek]

https://cms.skeeks.com/community/blog/322-kak-pisa... — тут можно посмотреть один из вариантов