Руководства - как актуально?

10

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

Брайан
источник
1
Мы говорим в печатном или электронном виде? Есть по крайней мере несколько различных форм, которые это может принять.
JB King
Электронные руководства (PDF)
Brian

Ответы:

4

Я бы обновил руководство:

  1. Для каждого основного выпуска и
  2. Когда важные новые функции становятся стабильными и достаточно зрелыми, чтобы вы знали, что они не будут меняться каждые пять минут.
Роберт Харви
источник
3

обновляйте руководство (PDF) каждый раз, когда изменение кода приведет к изменению инструкций в руководстве - просто сделайте обновление вручную частью процесса выпуска

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

Стивен А. Лоу
источник
1
так что если в штате нет технического писателя, то обновлять его самостоятельно?
Брайан
@ 0A0D - если у вас нет писателя, у вас нет большого выбора, если только у вас нет специалистов по тестированию или поддержке, которые могут это сделать.
Джефф
1
У меня есть документ «исходные файлы» как часть моих проектов. Они всегда обновляются одновременно с кодом. Они имеют версии с выпусками и управляются с использованием тех же исходных инструментов managmnet, что и остальные файлы проекта (перейдите на Mercurial!). У меня есть довольно стандартный набор руководств для проекта, и все они управляются одинаково (руководство пользователя, руководство по настройке / установке, примечания к выпуску и наши собственные технические документы / спецификации).
2

В 2010 году мы все еще ссылаемся на печатную документацию? Почему? ;)

Со всей серьезностью, документация (справка приложения «F1», PDF или онлайн-документация) должна быть частью каждого отдельного выпуска. Ноль оправданий. Это так просто "опубликовать". На самом деле, IMO, нет оправдания тому, чтобы не обновлять документацию на регулярной основе (онлайн и в формате PDF), даже между выпусками, как только проблемы будут известны и исправлены. Ему не нужен тот же уровень контроля качества - даже близко.

Марк Фридман
источник
2

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

Интегрируйте обновление документации в свой DoD ( определение сделано )

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

Вот определение сделано мы написали. Я пытался сохранить оригинальное форматирование, чтобы вы поняли. Это страница формата А4 на доске.

---------- 8 <------------ Cut Here ------------ 8 <----------

Не подлежит обсуждению

Определение «Готово»

  • Код с охватом модульных тестов 80%, зафиксированный в хранилище

  • Скриншоты, если применимо (1024x728, 395x281, 170x121 и 729x329)

  • Описание функций, если применимо (50 символов, 100 символов)

  • Полная документация для конечного пользователя

  • Что нового файла правильно обновлено

---------- 8 <------------ Cut Here ------------ 8 <----------

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

Одно из преимуществ определения «Готово», заключающегося в следующем, заключается в том, что ваш продукт может быть отправлен в конце каждого пользовательского рассказа.

Используйте эту технику в сочетании с этим .


источник
1

В моей организации у нас обычно есть 3 вида выпусков:

  1. Инженерный выпуск - в основном оперативное исправление для определенного клиента или какой-либо функции, которую только конкретный клиент запросил немедленно.
  2. Minor Release - исправлены ошибки, добавочная поддержка
  3. Major Release - поддержка новых функций и т. Д.

По определению, Major Release должен иметь соответствующую документацию как онлайн, так и офлайн. Наша система отслеживания гарантирует, что документация является частью контрольного списка.

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

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

Fanatic23
источник
0

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

SnoopDougieDoug
источник