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

Question

Я всегда думаю, что документ действительно важен для проекта и команды и должен быть написан регулярно и подробно . Это может заставить вещи идти параллельно, не всегда спрашивая опытных программистов здесь и там. Но на самом деле я нахожу, что многие разработчики (даже лидеры) не уделяют так много внимания документам, а просто принимают их как должное, что мне плохо.

Так правильно ли мое отношение к документам? Документы действительно важны? Как мне убедить руководителя группы уделять больше внимания документам?

Если документы важны, возникает второй вопрос. Кто должен писать документы? IMO, они должны быть написаны опытными программистами, такими как создатель фреймворка (если мы используем нашу собственную фреймворк), важные части проекта (такие как схема БД, вся архитектура и т. Д.) .) и не только.

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

Так что, по моему мнению, опытные программисты (определение здесь может отличаться) должны уделять больше внимания написанию документов, чем написанию кода после создания инфраструктуры.

Прав ли я в этом вопросе?

Спасибо, что поделились этими вопросами.

Answer 1

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

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

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

Что касается документации клиента, мои убеждения таковы:

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

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

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

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

Answer 2

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

Answer 3

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

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

Answer 4

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

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

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

Answer 5

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

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

Answer 6

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

Answer 7

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

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

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