Рекомендации, необходимые для написания спецификаций

Question

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

• Текущий Workflow: http://img80.imageshack.us/img80/102/currentworkflow.png

• Новый Workflow http://img245.imageshack.us/img245/6748/newworkflow.png

Я знаю, что они могли бы быть немного расплывчатым, но вот то, что в основном происходит. Мы добавляем новую форму импорта в существующее приложение Windows. Мы изменяем существующую форму, добавляя кнопку поиска, которая будет искать поиск и заполнение данных, прочитанных ocr.

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

Вот моя попытка спецификации. Может быть, кто-то может это критиковать. По крайней мере, тогда я буду знать, что мне нужно улучшить. http://cid-ddb3f6a92ec2b97e.skydrive.live.com/self.aspx/.Public/Specs.docx

Благодаря

Answer 1

Я люблю писать спецификации (я редкость в своей компании).

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

• Бизнес требование (краткий обзор о необходимости, как описано в бизнес, нетехнические пользователи)
• Примеров использования (как правило, для только больших спецификаций)
• Функциональных требований
  • Блок-схемы и т. Д.
  • Конфигурация
  • отчетов об ошибках
  • Тестирование
  • Документация
  • Обучение
  • Предположения и дополнительные ограничения
  • Сторонние Требования к программному обеспечению
  • Интернационализация
  • расширяемость (например, для битов, которые могли бы необходимо подключить к другим и т. д.)
  • Настройка
  • Вопросы (для вопросов, которые еще нужно ответить на кого-то, чтобы закончить спецификации)

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

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

EDIT: Комментарии your specification

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

• Если вы хотите, чтобы это было ясно понято бизнес-пользователем (например, клиентом), тогда раздел Objective может содержать предложение или два, описывающие проблему, которую он решает. Другими словами, не то, что достигнет, но почему.
• Здесь явно указано имя промежуточной промежуточной таблицы. По крайней мере, это означает, что если кто-то вернется к спецификации через год, они точно узнают, где искать в базе данных.
• Незначительный пункт: по моему опыту скриншоты, содержащие нереалистичные данные, сложнее понять. Вместо того, чтобы показывать «Моя примерная форма», «Имя», «Адрес» и т. Д., Возможно, было бы легче понять некоторые разумные данные. Все еще может быть подделкой для защиты данных клиента, таких как «123 Fake St» и т. Д. Не большая сделка.
• Непонятно, что произойдет, когда что-то пойдет не так. Должны ли быть какие-либо проверки того, что данные в промежуточной таблице находятся в допустимом формате? Если нет, выдается ли пользователю сообщение об ошибке или каким-то иным образом регистрируется? Одна ошибка в строке недопустимых данных или одна для всей партии?Форма состоит из одной кнопки - я думаю, что мы можем согласиться, это не самый большой пользовательский интерфейс в мире, но я понимаю, что иногда это происходит - возможно, его можно улучшить с помощью окна ведения журнала, чтобы показать результаты импорта. Ответы могут быть простыми, но разработчик должен знать, что они собой представляют.
  • Возможно, это не проблема в зависимости от того, сколько данных есть, но если их было много, и это займет некоторое время, возможно, стоит иметь индикатор выполнения. Или укажите, будут ли данные импортироваться поэтапно.
• Стоит ли упоминать определение постоянной таблицы, на которую перемещаются данные? Все поля перемещены из промежуточной таблицы в постоянную таблицу или только некоторые? Если только некоторые, можете ли вы показать, на каких картах что? Если постоянная таблица имеет разные длины данных - например, если Address Street является Varchar (30) - что произойдет, если данные не будут соответствовать? Опять же, возможно, простые ответы, но те, на которые было бы очень полезно ответить здесь.
• Возможно, стоит упомянуть, будут ли данные импортированы в одну транзакцию или нет - если импорт данных не проходит частично, если все откатывается или половина импортированных данных остается импортированной?
• Если другой разработчик выполнит эту работу, я думаю, что они далеки от, скорее всего, получим право работать, если вы издеваетесь или рисуете экраны для них. Даже если это всего лишь форма с одной кнопкой, и хотя я могу хорошо догадаться о том, как будет выглядеть ваша всплывающая форма поиска, я бы не ошиблась, если бы точно знала, как она должна выглядеть. Такие инструменты, как Balsamiq Mockups (и см. Примеры here), являются прекрасными для быстрых издевательств, хотя по умолчанию «комикс без» выглядит не очень хорошо с менеджерами. Я бы предпочел иметь грязный макет, чем вообще. (Примечание: бесплатная версия Balsamiq не позволяет вам сохранять изображения, но вы можете добиться того же результата с помощью функций экспорта/импорта. Также вы не можете сохранить файлы изображений, такие как PNG и т. Д., Но вы можете использовать экран- захватить программу, чтобы сфотографировать то, что вы рисуете.)
• Незначительный пункт: я стараюсь избегать личных местоимений типа «я», «мы», «наш», просто чтобы сделать его немного более профессиональным и лучше для клиентов прочитайте, если необходимо. Я заметил только одно «наше», поэтому вы в основном получили это право с точки зрения тона.
• Незначительная точка: достаточно ли varchars или будут там нестандартные символы, которые требуют unicode (т. Е. Nvarchar)?
• Мне не ясно, что происходит в форме добавления/обновления Voter, но у меня нет знания вашего приложения - возможно, все участники скажут «о, я понимаю». Например, я не понимаю значимости «ImpRecord001» и «ImpRecord002» - стоит ли в дизайне упомянуть, что эти пакетные коды фактически означают в реальном мире?
• Является ли кнопка «Поиск данных» такой же, как кнопка «Поиск OCR»?

Answer 2

Это отличный старт для спецификации.

Я бы добавил к ним, создав макет скриншотов того, что вы хотите, чтобы приложение Windows выглядело.

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

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

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

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

Answer 3

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

Answer 4

Для любого документа: сначала подумайте, почему вы его пишете - кто его прочтет, что им нужно знать? Сколько деталей подходит? Еще одна пара общих идей

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

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

Так что к вашему конкретному вопросу. Что вы подразумеваете под «spec»? Рабочий процесс, который вы даете, недостаточно для того, чтобы пользователь мог посмотреть и согласиться «Да, пожалуйста, это то, что я хочу». Недостаточно, чтобы кто-то написал код. Я думаю, вам может понадобиться несколько документов.

1). Некоторые требования doc. Один формат, который вы можете использовать, - это раскадровка. Это фокусируется на том, что пользователь может видеть и делать. Точно, какие данные отображаются на каждом экране. Если есть расчеты, лежащие в основе отображаемого, вам могут потребоваться приложения, описывающие их. Этот документ читается как пользователями, так и разработчиками. Powerpoint или Word могут использоваться.

2). Из этого вы можете получить некоторые явные модели данных. Поэтапный, по каждому полю. типы данных, размеры, валидацию и т. д. Я мог бы использовать инструмент моделирования даты, или UML или просто электронную таблицу. Первичная аудитория - разработчик, но в идеале пользователь (или бизнес-посредник) может проверить детали. [Если у вас нет бизнес-аналитика, вы, вероятно, : бизнес-аналитик :-)]

3). Более технический, спецификация для разработчиков, относящаяся к пунктам 1 & 2. Разложение реализации. Имена модулей, пакетов, классов или того, что вы используете. Определения преобразований, алгоритмов и вычислений. Более технический документ. Я бы использовал UML, но любая точная форма захвата. Здесь мы могли бы действительно развернуть то, что означает некоторые из подробных блоков в вашем рабочем потоке.

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