Spec Writing Management

9

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

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

Будет один или несколько сценариев:

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

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

Как вы управляете своими спецификациями? Я пытался заставить всех использовать Google Docs, но все возражали. Все слишком привязаны и очарованы Microsoft Word, который, по их мнению, очень прост в использовании, очень прост в вставке изображений, очень прост в наборе уравнений и так далее.

Как убедить их, что MS Word просто ужасен для обмена?

specifications Гравитон
источник

Ответы:

6

Как убедить их, что MS Word просто ужасен для обмена?

Не трать свое время.

Первый. Спецификация должна быть в открытом тексте (на самом деле) и под контролем исходного кода. Используйте Markdown или RST или другой легкий инструмент для разметки, чтобы создать страницу PDF или HTML. Простой текст.

Во-вторых. Возьмите различные источники. Слить их. Напишите свой собственный окончательный документ.

Когда они возражают, у них есть два варианта.

  1. Используйте Google Docs (или инструмент управления исходным кодом) для редактирования вашей версии.

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

Я предпочитаю № 2. Кто-то должен «владеть» спецификацией. И куча людей (в стиле вики) ведет к дебатам и войнам с изменениями, сопроводительным документам, автономным разговорам и тому подобному.

С. Лотт
источник
1
+1, и помните Правило Наименьшей Мощности - Любой, кто хочет модную версию в редакторе WYSIWYG, может просто скопировать визуализированную разметку.
10
@ l0b0: хорошая ссылка.
С.Лотт
6

Я не думаю, что это проблема «инструмента», а скорее проблема «процесса» (или отсутствия процесса).

Вероятно, у вас уже есть процесс выпуска программного обеспечения (модульное тестирование, интеграционное тестирование, письмо о выпуске, доставка и т. Д.), Вам также необходимо внедрить процесс документирования.

  • Кто собирается писать спецификации? Кто будет обновлять или поддерживать их?
  • Кто будет пересматривать спецификации?
  • Кто собирается утверждать спецификации? Архитектор, Руководитель проекта, QA?
  • Как хранятся спецификации?
  • Кто будет следить за тем, чтобы не использовались устаревшие версии?
Ксавье Т.
источник
2
+1: проблемы с инструментом часто являются признаками проблем процесса.
С.Лотт
У нас действительно есть процесс, но люди просто любят жаловаться, что этот процесс не работает и по возможности срезать углы.
Гравитон
@Graviton: ваша главная проблема, вероятно, в том, что руководство не видит использования документации и, следовательно, не применяет строгие правила. Если вы хотите, чтобы вещи улучшились, вам, вероятно, придется показать им, насколько это важно.
Ксавье Т.
4

Какой-то контроль обязательно требуется.

Он должен быть версионным и подписанным, и этот процесс должен быть строгим.

В слишком многих местах подписание игнорируется, и это приводит к дракам с булочками.

Местоположение не имеет значения, пока его можно отслеживать

  • Sharepoint
  • безопасный резервный общий диск
  • Я видел, как некоторые места используют свой контроль исходного кода!

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

Ozz
источник
+1, я настоятельно рекомендую перенести спецификацию в систему контроля версий, если больше ничего не помогает. Одним из преимуществ является то, что вы получаете историю версий. Даже если вы не можете делать сравнения версий (если вы не найдете плагин, который может делать сравнения для файлов Word), вы все равно можете извлечь всю версию и посмотреть, что изменилось. Это может быть ОЧЕНЬ полезно в споре о спецификациях. Подписание тоже очень хорошо иметь. А также важность привлечения всех участников к процессу (чтобы никто не мог сказать «когда это было решено?») Не может быть подчеркнута.
FrustratedWithFormsDesigner
0

MS Word идеально подходит для создания спецификации. Мы управляем нашим в SharePoint, который также управляет версиями. Если у вас нет SharePoint или другого удобного продукта для управления документами, с Google Docs все в порядке (теперь вы можете загружать файлы .doc / .docx без преобразования их в формат Google Docs). Или, как другие предложили, вы даже можете сохранить их в своей системе контроля версий исходного кода (если люди, создающие спецификации, имеют доступ к этой системе).

Марси
источник
0 
 > How to convince them that MS Word is just terrible for sharing?

Вы не можете легко сравнить разницу двух экземпляров в системе контроля версий.

По этой причине я не люблю спецификации слов. Но так как это политическое решение использовать спецификации слов, мы имеем в качестве первой страницы «историческую информацию» с этими столбцами:

номер версии (относится к версии продукта), автор, дата, описание

k3b
источник