Один из элементов в Joel Test заключается в том, что проект/компания должны иметь спецификацию.
Мне интересно, что делает спекулянт хорошим. Некоторые компании будут писать тома бесполезной спецификации, которую никто не читает, другие ничего не напишут, потому что "никто ее не прочитает". Итак, что вы вкладываете в свою спецификацию? Каков хороший баланс между двумя крайностями? Есть ли что-то особенно важное, что действительно, действительно (!) Всегда должно быть записано в спецификации?
Лучшая спецификация - та, которая:
Что добавить в спецификацию
Вам нужно взглянуть на аудиторию спектакля и выяснить, что им нужно знать. Это всего лишь документ между вами и бизнес-спонсором? В этом случае он может быть довольно легким. Если это функциональная спецификация для 100+ человеко-летнего проекта J2EE, она, вероятно, понадобится немного подробнее.
Аудитория
Ключевой вопрос: кто будет читать спецификацию? В спецификации будет несколько потенциальных групп заинтересованных сторон:
Владелец бизнеса, который подписывает от системы.
Разработчик, который строит система (которая может быть или не быть вами)
QA люди, которым приходится писать планы тестирования для него.
Сотрудники службы поддержки, желающие понять систему
Разработчики или аналитики по другим проектам, которые может захотеть интегрировать в него другие системы.
Требования к основным заинтересованным сторонам:
Владелец должен иметь четкое представление о том, что происходит с бизнес-процессами и бизнес-правилами системы, поэтому они могут иметь шанс сражаться за понимание того, что они согласились. Если они являются единственной основной аудиторией спецификации, сосредоточьтесь на пользовательском интерфейсе, рабочем процессе экрана и правилах проверки бизнеса и данных.
Разработчики нуждаются в модели данных, правилах проверки данных, некоторых или всех конструкциях пользовательского интерфейса и достаточном описании ожидаемого поведения системы, чтобы они знали, что строить. Если вы пишете для разработчиков, сосредоточьтесь на пользовательском интерфейсе, сопоставление модели данных и правил в пользовательском интерфейсе. Это должно быть более подробным, чем если вы сами делаете разработку, потому что вы выступаете в качестве посредника в общении между двумя третьими сторонами.
Если вы указываете интерфейс между двумя системами, это должно быть очень точным.
Сотрудники QA нуждаются в достаточной информации, чтобы определить, как тестировать и проверять логику, проверку и ожидаемое поведение пользовательского интерфейса приложения. Спецификация, предназначенная для разработчиков и персонала QA, должна быть достаточно однозначной.
Сотрудники службы поддержки нуждаются во многом такой же информации, что и разработчики, а также документ дорожной карты системы, описывающий архитектуру.
Интеграторы нуждаются в модели данных и четких определениях любых интерфейсов.
Ключевые компоненты спецификации:
Я предполагаю, что вы пишете спецификации для бизнес-приложений, поэтому приведенный ниже контент ориентирован на это. Спецификации для других типов систем будут иметь различный акцент. По моему опыту ключевыми элементами функциональной спецификации являются:
Интерфейс пользователя:, а также описание поведения взаимодействия системы и рабочего процесса между экранами.
Модель данных: Определение элементов данных и отображение в пользовательский интерфейс. Отображения пользовательского интерфейса обычно выполняются в битах спецификации, описывающих пользовательский интерфейс.
Проверка данных и бизнес-правила:. Какие проверки правильности необходимо делать с данными и какие вычисления производятся вместе с определениями. Примеры здесь могут быть весьма полезными.
Определения интерфейсов:. Если у вас есть интерфейсы, которые могут использовать другие системы, вам нужно указать их довольно сильно. Более простой интернет-RFC дает неплохие примеры конструкций протоколов и является хорошим началом для примеров документов интерфейса. Четкое определение интерфейсов непросто, но почти наверняка спасет вас от горя.
Клей:, где используются прецеденты, диаграммы рабочего процесса и другие требования, связанные с артефактами. Как правило, их исчерпывающий список бессмысленен, но в системе есть ключевые области, где этот тип документации помогает помещать элементы в контекст. Мой опыт заключается в том, что выборочное включение прецедентов и других описаний уровня требований делает многое, чтобы добавить ясность и смысл в спецификацию, но создание истории пользователей для каждого отдельного взаимодействия с системой - пустая трата времени.
Joel (из 'on software' fame) написал хорошую серию статейна этом названном функциональном описании из нержавеющей стали, о котором я неоднократно говорил людям. Это довольно хороший набор статей и стоит прочитать. На мой взгляд, ваша цель - четко объяснить, что система должна делать так, чтобы минимизировать двусмысленность. Очень полезно придумать спецификацию в качестве справочного документа - что могут заинтересовать различные заинтересованные стороны, чтобы они могли легко искать.
Написав набор точек с маркером о спецификациях, четкая коммуникационная часть сложнее, чем кажется. Спецификации на самом деле являются нетривиальными техническими документами и достаточно проверены на одно техническое письмо и редакционные навыки. Фактически вы занимаетесь написанием документа, который описывает, что кто-то должен строить. Выполнение хороших характеристик - это немного искусства.
Выплаты за выполнение спецификаций заключаются в том, что никто не хочет их делать. Поскольку вы написали, что, вероятно, единственный документ, имеющий какое-либо значение для системы, вы можете вызвать снимки. Любой, кто имеет повестку дня, должен либо лоббировать, чтобы вы меняли спецификацию, либо каким-то образом навязывали конкурирующие спецификации в проекте. Это хороший пример того, что перо было сильнее меча.
РЕДАКТИРОВАТЬ:. Мой опыт состоял в том, что дебаты о различии между "как" и "тем, что" имеют тенденцию быть довольно самообслуживающими. В любом нетривиальном проекте модель данных и пользовательский интерфейс будут иметь несколько заинтересованных сторон, не все из которых являются разработчиками системы. Работа в хранилище данных даст один вкус к хаосу, который возникает, когда модель данных приложения может стать бесплатной для всех, и PFS должен дать возможность почувствовать потенциальный набор заинтересованных сторон, к которому должен удовлетворять спецификация.
Тот факт, что кто-то владеет моделью данных или дизайном пользовательского интерфейса, не означает, что они просто решены с помощью fiat - может быть дискуссия и процесс переговоров. Однако, по мере того как проект становится больше, ценность владения и согласованности в них возрастает. Это было моим наблюдением в прошлом, что лучший способ оценить ценность хорошего аналитика - это увидеть ущерб, нанесенный плохим.
По моему опыту спецификация будет иметь больше шансов быть прочитанной, если она имеет следующее:
Я видел в компаниях, где человек, написавший спецификацию, не понимает систему. Это почти способ обучения системы, написав спецификацию. Это обычно заканчивается слезами...
Как кто-то, кто разрабатывает индивидуальное программное обеспечение для клиентов, лучшая спецификация - та, которую клиент подписал.
Не имеет значения, насколько утончена ваша спецификация - если клиент явно не согласился на это в письменной форме, они изменят ее и ожидают, что вы сможете легко перевернуть свои изменения, разрушив красивую архитектуру...
Хорошие спецификации должны содержать требования, которые поддаются измерению и поддаются проверке. Рассматривая каждое требование, вы должны легко ответить на вопрос: "Как я могу доказать, что выполнил это требование?".
Прочитайте серию Joel "" Безболезненные функциональные характеристики ", посвященные статье Joel Test. Они также появляются в книге" Joel on Software".
В зависимости от того, насколько велик проект и (как и все решения по архитектуре), какие существуют ограничения. Хорошее начало -
Лучше всего иметь приемочный тест, т.е. проверяемое утверждение вещей, которое можно проверить, а также соглашение о том, что когда все будет сделано, проект будет завершен.
Это также помогает, если вы начинаете с определения цели, которой обладает пользователь, или того, что представляет собой глобальная идея определенной функции; а не заполнять точную реализацию. Мне всегда кажется, что это сужение открытой мысли или использование менее творческих (более пригодных для использования) решений. Поэтому вы должны оставить "все варианты открытыми".
Пример Вы пишете программное обеспечение для измерения "X".
Вместо того, чтобы заявлять: Должна быть кнопка запуска и кнопка сохранения.
Использование: Пользователь должен иметь возможность начать измерение и сохранить его.
Почему? Потому что в первой ситуации вы уже определили, какое решение должно быть, а вторая ситуация дает вам гибкость в как, чтобы реализовать что-то. Теперь это может показаться тривиальным, но у меня есть ощущение, что "программисты" склонны больше думать о решениях, а не о проблемах (или ситуациях). Когда вы добавляете больше функциональности, это становится более очевидным, потому что тогда было бы лучше использовать мастер или автоматизировать процесс, но вы уже сузили идею до использования кнопок.
Для функциональных требований, а точнее, поведенческих требований - мне нравится использовать огурец и огурчик.
Вот пример простой и короткой спецификации новой функции в простом приложении сопоставления. Эта функция позволяет малым предприятиям подписываться на картографическую платформу и добавлять свои коммерческие объекты в сервисы 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. Theyre наилучшим образом служил кратко и просто. Вместо того, чтобы писать длинный справочный документ, вы даете набор спецификаций развиваться вместе с вашим продуктом, написав новые спецификации на каждой итерации.
Gherkin - это бизнес-читаемый язык для написания спецификационных документов на основе шаблона Given-When-Then. Шаблон может быть автоматизирован в приемочные испытания. Автоматизация спецификации обеспечивает ее актуальность, поскольку захваченный разговор напрямую привязан к тестовому коду. Таким образом, тесты могут использоваться как документация, потому что функции Gherkin должны меняться каждый раз, когда изменяется код.
Когда каждому бизнес-правилу предоставляется автоматизированный тест, спецификации Gherkin становятся так называемыми исполняемыми спецификациями-спецификациями, которые могут выполняться как компьютерные программы. Программа проверяет правильность внедрения критериев приемки. Поэтому в конце дня мы получаем ответ "да" или "нет" на вопрос о том, действительно ли наш продукт делает то, что мы ожидаем от него, что само по себе очень ценно, поскольку оно способствует созданию программного обеспечения лучшего качества.
Прямая связь между спецификациями Gherkin и кодом тестирования часто снижает ущерб от отходов, создавая и совершенствуя систему живой документации. Благодаря частой проверке тестов, как и в системах непрерывной интеграции, вы можете знать, что данные "когда-то-потом" по-прежнему актуальны, и когда вы доверяете своим тестам, вы можете использовать соответствующие спецификации Gherkin в качестве документации для всей системы.
Фактически, существует целая методология под названием Specification by Example, в которой используются такие инструменты, как Gherkin. Спецификация по примерам снижает вероятность недоразумений и переделок, предоставляя вам основу для общения с заинтересованными сторонами бизнеса, заставляя вас использовать конкретные, дискретные, недвусмысленные примеры в ваших спецификационных документах.
Если вы хотите больше узнать о Cucumber, Gherkin, BDD и Specification by Example, я написал книгу по этому вопросу. "Написание отличных спецификаций" исследует искусство написания замечательных сценариев и поможет вам сделать исполняемые спецификации основной частью вашего процесса разработки.
Если вы заинтересованы в покупке "Написание отличных спецификаций", вы можете сохранить 39% с промо-кодом 39nicieja2:)
Я думаю, что запись "Использование случаев" должна сэкономить вам кучу страниц
+1 @KiwiBastard, и я добавлю пилюлю типа bullet-like и сделаю каждую пробную версию пули.
Схема, которая описывает всю критическую информацию, необходимую для реализации, но не тратит никаких усилий на описание всей тривиальной или очевидной информации, которая также необходима.
Это должно быть достаточно информации, чтобы гарантировать, что реализация "как ожидалось", без лишних дополнительных шумов, которые не нужны.
На практике большинство людей ошибаются, поскольку они сосредоточены на легком материале (который является наименее необходимым) и уклоняются от тяжелого материала (именно этого вы действительно хотите заблокировать). Я видел слишком много двухдюймовых документов, которые полностью и полностью упускают из виду, и очень немногие 3 страницы, на которых он мертв.
Спекуляции не должны быть длинными, они просто должны содержать правильные вещи!
(подсказка: если программист не смотрел на эту страницу во время кодирования, это, вероятно, не требовалось)
Павел.