Документы для проекта?

Ответ 1

Ключевым документом является хорошая функциональная спецификация. Должен быть один и только один справочный документ для система.

Документация Overdoing распространяется на большое количество небольших требований и специфицированных документов каждый раз, когда кто-то меняет систему или интерфейс. Для системы любой сложности, вскоре у вас есть своя спецификация, распределенная вокруг нескольких сотен различных слов, excel, visio и даже файлов PowerPoint. Когда это происходит, вы теряете ясность относительно того, что является актуальным или даже если вы нашли и идентифицировали всю соответствующую документацию.

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

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

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

Ответ 2

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

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

Ответ 3

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

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

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

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

Ответ 4

Как вы думаете, какие наиболее важные документы для проекта?

У разных людей разные потребности: например, документы, которые требуется владельцу (например, бизнес-контракт), не совпадают с документами, требуемыми QA.

Какие документы можно использовать в долгосрочной перспективе другим разработчиком?

IMO самым важным документом (за исключением исходного кода) является функциональная спецификация: поскольку то, что программное обеспечение предполагается делать (в отличие от того, что это делать) - это единственное, что не обязательно может быть обратное проектирование. См. Также Как хороший разработчик не может создавать код с низким коэффициентом попадания шины?

Ответ 5

Истории пользователей, диаграмма выгорания, код

Ответ 6

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

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

Обычно обычно смотрят на вещи с его собственной точки зрения, иногда приходится смотреть на общую картину.

Ответ 7

Я поклонник старых просмотров 4 + 1:

• Использовать вид приложения (рассказы пользователя /k/a ). Существует несколько форм: правильные варианты использования, перспективные варианты использования, которые не так четко определены, и эпики, которые необходимо разложить.

• Логическое представление. "Статический" вид. Диаграммы классов UML и тому подобное хорошо работают здесь как дизайн-документ. Это также включает форматы запросов и ответов для различных протоколов. Здесь мы документируем запросы и ответы RESTful. Это включает в себя дизайн REST URI.

• Вид процесса. "Динамический" вид. Диаграммы активности UML, диаграммы последовательности и диаграммы состояния и т.д. Для проектных документов. В некоторых случаях простые нарративы работают хорошо. В других случаях существует конструктивный шаблон State, и для его отображения требуется сочетание диаграмм классов и диаграмм состояния, чтобы показать, как взаимодействуют объекты состояния.

  Это также включает протоколы (например, REST). Здесь мы определяем любую специальную обработку для различных запросов REST.

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

• Просмотр компонентов. Части, которые мы собираем для развертывания. Это включает в себя материал, от которого мы зависим, структура модулей и пакетов и т.д. Это часто простая диаграмма компонентов или список компонентов и их зависимости.

• Вид развертывания. Мы пытаемся сгенерировать это из кода как развернутого. Поскольку мы используем Python, мы используем epydoc для создания документации API. Мы также используем Sphinx для импорта документации модуля в этот вид программного обеспечения.

  Это также включает параметры, настройки и детали конфигурации.

Этого, однако, недостаточно.

Когда проекты начинаются, вы должны работать над этим с помощью серии спринтов.

• Первые спринты строят только вид использования.

• Последующие спринты создают "архитектуру" для реализации вариантов использования. Документ архитектуры имеет 4 + 1 просмотров, но на высоком уровне абстракции. Он суммирует структуру схем модели, запросы и ответы, обработку RESTful, другую обработку, ожидаемую компоненту и т.д. Он никогда не имеет вида развертывания. Обычно мы ссылаемся на руководство оператора и документы API как на представление архитектуры развертывания.

• Затем проектно-строительные спринты строят (и обновляют) подробные документы 4 + 1 для различных компонентов.

• Затем отпустите sprints для сборки (и обновления) представлений развертывания.