Что делает хорошую спецификацию? [закрыто]

Один из пунктов вДжоэл Тест является то, что проект / компания должна иметь спецификацию.

Мне интересно, что делает спецификацию хорошей. Некоторые компании будут писать тома бесполезных спецификаций, которые никто никогда не читает, другие не будут ничего записывать, потому что «все равно никто не будет читать». Итак, что вы вкладываете в свою спецификацию? Каков хороший баланс между двумя крайностями? Есть ли что-то особенно важное, что действительно, действительно (!) Всегда должно быть записано в спецификации?

 Talon29 янв. 2016 г., 07:15
Я знаю, что это старый пост, но у меня будет 2с. Джоэл написал статью под названием «Безболезненные функциональные характеристики». Он описывает тот факт, что независимо от того, читает ли это кто-либо или нет, важно то, что для его написания вам, скорее всего, нужно было собрать всех вместе и подумать о каждом компоненте. Спецификация в этом отношении может просто рассматриваться как «Протокол встречи».

Ответы на вопрос(12)

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

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

 Hugo Sereno Ferreira19 дек. 2008 г., 01:54
Да ... И после того, как они подписывают это, они говорят: ну, мы не поняли это так, как вы, так что ... Красивая архитектура - это та, которая будет адаптироваться к их изменениям. Обними их, не отрицай ;-)

Безболезненные функциональные характеристики"продолжение статьи Joel Test. Они также появляются в книге" Joel on Software ".

насколько велик проект и (как и все архитектурные решения), каковы ограничения. Хорошее начало

краткое описание, «один пейджер»контекстная диаграмма - где границы, что взаимодействует с системой?сценарии использования / истории пользователейпрототип GUI или бумажный прототип, если применимоописание необходимых нефункциональных требований (производительность и т. д.)

Лучше всего пройти приемочный тест, т. Е. Тестируемое заявление о том, что можно проверить, и согласие с тем, что когда все это будет сделано, проект будет завершен.

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

пример Вы пишете программное обеспечение для измерения "X".

Вместо указания: должна быть кнопка запуска и кнопка сохранения.

Использование: пользователь должен иметь возможность начать измерение и сохранить его.

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

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

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

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

Спецификации не должны быть длинными, они просто должны содержать нужные вещи!

(подсказка: если программист не смотрел на эту страницу во время кодирования, это, вероятно, не требовалось)

Павел.

спецификация будет иметь больше шансов на чтение, если она имеет следующее:

По возможности используйте диаграммы - картинки стоят 1000 словИмейте титульный лист, который ясно указывает, что спецификация описываетИмейте стиль, который используется всюду по документу. Сделайте все заголовки одинаковыми шрифтом, размером и стилем. Сделайте шрифт одинаковым на всем протяжении, используйте одинаковые стили маркеров и т. Д.Не делайте вафли - будьте четкими и лаконичными, не добавляйте лишних слов, чтобы раскладывать документ. Если точка не может быть объяснена в нескольких строках текста, то, возможно, вам нужно разбить ее дальше

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

 Alvaro Rodriguez18 дек. 2008 г., 23:44
Диаграммы не доступны для поиска. Если у вас есть сто диаграмм, как вы будете искать информацию, содержащуюся в них? Вы можете искать по тексту ...
 Brian B.19 дек. 2008 г., 02:15
Я предпочитаю текстовые описания. Но это мое предпочтение, все, что я говорю, не пропустите описание, потому что у вас есть диаграмма. Не все видят вещи одинаково.
 Connor Doyle12 февр. 2015 г., 17:02
Диаграммы ASCII доступны для поиска!
 JamesSugrue19 дек. 2008 г., 00:23
Дайте диаграмме полезный заголовок в тексте. Если у вас есть много слов вместо этого, поиск будет ничем не отличаться, так как вы все равно будете искать по ключевым словам

что написание «вариантов использования» должно спасти вас кучу страниц

Что поставить в спецификации

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

Аудитория

Ключевой вопрос: кто будет читать спецификацию? Спецификация будет иметь несколько потенциальных групп заинтересованных сторон:

Владелец бизнеса, который выходит из системы.

Разработчик, который строит систему (кто может быть, а кто нет)

QA люди, которые должны написать планы испытаний для этого.

Обслуживающий персонал, желающий понять систему

Разработчики или аналитики других проектов, которые могут захотеть интегрировать в него другие системы.

Требования типичных ключевых заинтересованных сторон:

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

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

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

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

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

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

Ключевые компоненты спецификации:

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

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

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

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

Определения интерфейсов: Если у вас есть открытые интерфейсы, которые могут использовать другие системы, вам нужно довольно точно их указать. Более простые интернет-RFC дают довольно хорошие примеры проектов протоколов и являются хорошим началом для примеров документов интерфейса. Четко определить интерфейсы непросто, но почти наверняка избавит вас от горя.

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

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

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

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

РЕДАКТИРОВАТЬ: По моему опыту, спор о разнице между «как» и «что» имеет тенденцию быть довольно корыстным. В любом нетривиальном проекте модель данных и пользовательский интерфейс будут иметь несколько заинтересованных сторон, не все из которых являются разработчиками системы. Работа в хранилище данных даст представление о хаосе, который возникает, когда модели данных приложения разрешено стать бесплатной для всех, иPFS Должен дать представление о потенциальном круге заинтересованных сторон, которым должна соответствовать спецификация.

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

 Robert C. Barth18 дек. 2008 г., 23:51
Я не согласен с моделью данных и пользовательским интерфейсом. Те описывают "как". Спецификация описывает только «что». Захват элементов данных отличается от создания модели данных.
 ConcernedOfTunbridgeWells22 июл. 2009 г., 10:52
Кто-то должен спроектировать модель данных и пользовательский интерфейс, и будет много веселья, если любой из них станет бесплатным для всех. Отчеты и MIS часто являются бедными родственниками в этом отношении. Я знаю одну европейскую телекоммуникационную компанию, в которой 800 человек работают только в одном из своих подразделений хранилищ данных (мобильное подразделение имеет собственный отдел хранилищ данных) - в основном из-за плохой архитектуры данных. Я также знаю о компании, продающей финансовое программное обеспечение, которое по сути обанкротилось из-за совокупной стоимости владения ее системы, обусловленной постоянным исправлением данных.

KiwiBastard и я хотел бы добавить запись пули как и сделать каждую пулю тестируемой.

 JsonStatham12 авг. 2013 г., 16:04
Я уверен, что это должен быть комментарий, а не ответ

которые измеримы и проверяемы. Рассматривая каждое требование, вы должны легко ответить на вопрос «Как я могу доказать, что я выполнил это требование?».

Решение Вопроса

СуществуетОписывает ЧТО, а не КАК (без решений)Может интерпретироваться как можно меньшеШироко распространенСогласовано как спецификация всеми вовлеченными сторонамиСжатСогласуетсяОбновляется регулярно по мере изменения требованийОписывает столько проблем, сколько возможно и практичноТестируемый
 Hugo Sereno Ferreira19 дек. 2008 г., 01:52
Увы, наконец, кто-то, кто понимает цель спецификации.
 Robert C. Barth20 дек. 2008 г., 01:45
Я немного расширил этот список в блоге, если кому-то интересно.norimek.com/blog

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

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

Feature: Allow new businesses to appear on the map

  Scenario Outline: Businesses should provide required data

    Given a <business> at <location>
     When <business> signs up to the map platform
     Then it <should?> be added to the platform
      And its name <should?> appear on the map at <location>

    Examples: Business name and location should be required
      | business         | location | should?   |
      | UNNAMED BUSINESS | NOWHERE  | shouldn't |

    Examples: Allow only businesses with correct names
      | business         | location                  | should?   |
      | Back to Black    | 8114 2nd Street, Stockton | should    |
      | UNNAMED BUSINESS | 8114 2nd Street, Stockton | shouldn't |

    Examples: Allow businesses with two or more establishments
      | business      | location                | should? |
      | Deep Lemon    | 6750 Street South, Reno | should  |
      | Deep Lemon    | 289 Laurel Drive, Reno  | should  |

    Examples: Allow only suitable locations
      | business      | location                | should?   |
      | Anchor        | 77 Chapel Road, Chicago | should    |
      | Anchor        | Chicago River, Chicago  | shouldn't |
      | Anchor        | NOWHERE                 | shouldn't |

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

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

Gherkin - это читаемый бизнес язык для написания спецификационных документов на основе шаблона Given-When-Then. Шаблон может быть автоматизирован в приемочные испытания. Автоматизация спецификации гарантирует ее актуальность, поскольку захваченный диалог напрямую связан с тестированием кода. Таким образом, тесты могут использоваться в качестве документации, потому что функции Gherkin должны меняться каждый раз, когда изменяется код.

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

Прямая связь между спецификациями Gherkin и кодом тестирования часто снижает ущерб от отходов, создавая и развивая систему живой документации. Благодаря частой проверке тестов, как и в системах непрерывной интеграции, вы можете знать, что Given-When-Thens все еще актуальны, а когда вы доверяете своим тестам, вы можете использовать соответствующие спецификации Gherkin в качестве документации для всей системы.

На самом деле, существует целая методология под названием «Спецификация на примере», в которой используются такие инструменты, как Gherkin. Практика Specification by Example уменьшает вероятность недоразумений и доработок, предоставляя вам основу для общения с заинтересованными сторонами бизнеса, заставляя вас использовать конкретные, дискретные, недвусмысленные примеры в ваших документах спецификаций.

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

Если вы заинтересованы в покупке «Написание отличных спецификаций», вы можетесэкономьте 39% с промо-кодом 39nicieja2 :)

Ваш ответ на вопрос