Документы должны быть записаны квалифицированными программистами?

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

Важные вопросы, которые следует задать по поводу любой потенциальной документации: какова цель, предполагаемое использование и ожидаемая частота использования документации? Вы упомянули помощь новичку, но на практике ли чтение документации быстрее и эффективнее, чем получение пошагового руководства от другого разработчика? Пошаговое руководство требует времени от другого разработчика, но, вероятно, гораздо меньше времени, чем на написание документа.

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

Вы не ошиблись, но факт в том, что документация не приносит денег. Во всяком случае, плохая документация может увеличить доход, потому что вы убедились, что клиентам понадобится ваш контракт на поддержку.

Документирование также является проблемой, потому что теоретически это должно быть сделано до разработки , но на самом деле все измените, поэтому действительно стоит создавать / обновлять только после выпуска основной версии.

В идеале автором должен быть бизнес-аналитик, не разработчик.

Ваша группа должна создать процесс разработки программного обеспечения, который определяет, как вы будете разрабатывать свои программные продукты. Часть этого процесса будет определять документы, которые будут написаны, и, по моему опыту, все члены команды разработчиков участвуют в процессе документирования - это может (и должен) быть процесс обучения.

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

В Интернете есть множество примеров процессов, от очень легких до очень тяжелых.

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

У вас есть несколько видов документации, за один из которых вы отвечаете:

Документируйте каждую функцию, класс, структуру, член по мере ее заполнения

В идеале, вы делаете это в способ, позволяющий автоматически извлекать исходную документацию (например, Doxygen). Просто убедитесь, что делаете это на ходу.

Что касается документации для клиентов, я считаю:

• Каждая фирма-разработчик должна нанимать тестировщиков
• Тестировщики должны вносить большой вклад в процесс документации

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

Что касается тестировщиков, они действительно ваши лучшие друзья (или должны им быть). Это люди, которые знают, как работает ваше программное обеспечение, почти так же хорошо, как и вы. И да, я согласен, у вас должен быть хотя бы набросок функциональности программы, чтобы вы не отклонились от касательных «добавленной стоимости». Просто имеет смысл позволить тестировщикам заполнить это поле, а затем попросить разработчиков проверить его на точность.

Вы можете даже обнаружить, что вы говорите: « Нет-нет-нет ... это не работает, что Кстати ... тестировщики ошиблись ... ", затем вы запускаете приложение, чтобы понять, что они все поняли :) В этом аспекте это также полезно для процесса контроля качества.