Как правильно писать документацию проекта?

Question

[Алекс Понтик]

В данный момент разрабатываем проект, пишем все с нуля. Разработкой занимаются два программиста.
В проект планируем взять еще 2-3 человек, вот у меня и стал вопрос - как правильно писать документцию, чтобы только-что пришедший человек не дергал сильно программеров, которые работают, а почитал доки и начал работать.

Может быть еще ситуация, что программист, который писал проект завтра уйдет - а информации нет.

Прошу, подскажите, как вы организуете процесс написания доков. Как много времени на это тратится и кто этим занимается.

Comments

[1001001 111]

Ну как вариант посмотрите в сторону UML + написание кода в едином стиле

[kazmiruk]

Neoline: ну-ну ) Тогда предлагаю вам скачать исходник постгрес и разбираться в них без чтения документации.

Answer 1

[Робот]

Да просто подсмотрите в рабочем проекте например www.tinymce.com/wiki.php/Configuration
Только с поправкой что для разработчиков пишете а не для юзеров.
Какие блоки, классы за что отвечают вкратце, где костыли которые желательно переписать, объяснить где тут сторонние модули если есть, магию объяснить если имеется в проекте.

Answer 2

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

В больших компаниях (или при отлаженных процессах) этим занимается т.н. Технический писатель (Technical Writer). Далее я вам подскажу, как надо делать "по уму" без разных XP-техник и т.п. Прислушиваться к советам или нет - будете решать сами.

В вашем случае, думаю, брать TWR смысла нет, т.к. коллектив маленький/процессы еще не отлажены. Вы, конечно, можете взять TWR для постановки процесса документирования в вашей компании, но специалисты этого уровня - это Lead Technical Writer и его расходы на него будут сравнимы с уровнем разработчика. Сразу же говорю, что никакой студент-техпис вам работу не поставит.

Чтобы понять, что и как вам надо делать, попробуйте сами себе ответить на следующие вопросы. Я адресовал их другим участникам:
Как документировать существующее решение?
https://toster.ru/answer?answer_id=658763
https://toster.ru/answer?answer_id=658763

Имейте в виду, что некоторые участники в тех тредах с трудом анализируют информацию :)

Можете опубликовать ответы на заданные вопросы здесь, и я постараюсь подсказать вам возможные решения.

Answer 3

[abukirev]

На мой взгляд для команды из 4-5 программистов не нужен технический писатель. Вы ведь не SDK или еще чего подобное разрабатываете, которое пойдет наружу сотням-тысячам пользователей...

На сколько я понял речь идет о внутренней документации для разработчиков. И в этом случае подойдут простые и проверенные решения как:
- Документирование исходного кода. Инструменты типа Doxygen вам в помощь
- Документирование каких-то особенностей вне кода. Любые варианты wiki вам помогут. Например, MediaWiki
- Документирование архитектурных решений. Можно использовать различные инструменты для UML проектирования, типа StarUML или Umbrello
- Дополнительно можно задокументировать разные API и прочие штуки которые не попали в предыдущие части. Для этого вполне подойдет или wiki или те же google docs.

Ну и конечно же не забудьте использовать систему контроля версий исходного кода и придерживаться принципа атомарности коммитов, тогда это тоже будет не плохим подспорьем.

Answer 4

[Тим]

Почитал доки и начал работать, это надо документировать процессы. От того где взять задачу, какие правила по её разработке, сдаче, тестировании. Правила владения кодом, комментирования, рефакторинга, работы с ветками, выкатками, кодейстайлом.