Процесс написания технической спецификации

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

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

Большинство ответов на документацию, по-видимому, предполагают, что после получения подробного списка требований разработчики будут знать наилучший возможный способ ее реализации, и я склонен обнаруживать, что это часто бывает не так. Лучший ресурс, который я нашел до сих пор, кажется, 10 * Разработка программного обеспечения Стивом Макконнелом, но мне было интересно, есть ли у кого-нибудь какие-то полезные ответы.

Ответы

Ответ 1

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

Мой подход состоял бы в том, чтобы взять определенную часть системы, что выполняет все технические уровни - DB, UI, Web-сервисы и документирует, как это должно быть реализовано, возможно, используя диаграммы классов, возможно, просто предлагая конкретные библиотеки и подходы. Таким образом, ваша техническая спецификация не слишком велика, дополняет и расширяет документ архитектуры (который может быть списком маркеров, если вы не хотите слишком много doco).

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

Ответ 2

Я собираюсь предложить прочитать серии Joel, начиная с Безболезненные функциональные характеристики - Часть 1: Зачем беспокоиться? У него даже есть ссылка на Спецификация проекта Aardark (теперь Copilot), которую вы можете загрузить и прочитать в качестве примера того, что делает хорошую спецификацию.

Одно очко: вы упоминаете как технические, так и функциональные спецификации в своем сообщении. Там разница.

Вы касаетесь вопроса о стандартах кодирования, как это кажется (и).

Лично я предпочитаю подход на основе Wiki для чисто технической документации. Разработчики jsut не любят писать большие документы Word. Wikis позволяет писать материал, сотрудничать, вставлять диаграммы классов или что угодно.

Я нашел дополнительную информацию об этом, например, эту тему о технические и функциональные спецификации, где Джоэл пишет:

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

Так что техническая спецификация не срабатывает существующий. В этом месте вы можете или можете не иметь нескольких технических статей о небольшие темы:

и

Помните, что вы говорите о влиянии на пользовательский интерфейс или даже поведение вещи, которую вы он работает в функциональном spec... так что все, что осталось техническая спецификация - это вещи, которые СОБСТВЕННО программистов, и, по сути, много этот материал может быть лучше всего в комментариях, так что, самое большее, у вас должно быть несколько коротких статей по таким темам, как алгоритмы - и вы пишете эти статьи по требованию, когда вам нужно продумать дизайн или документ "большая картина" для будущего программистов, чтобы они не выяснить, что ваш код пытается выполнить.

который описывает это гораздо более красноречиво, чем I.

Ответ 3

Две мысли:

Наиболее полезным способом, который я знаю для связи о предлагаемой реализации, является использование диаграмм классов и диаграмм последовательности.

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

Ответ 4

Я думаю, что это сводится к определенным основам дизайна:

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

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

Некоторые примеры методов проектирования для определения наилучших возможных вариантов:

Ответ 5

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