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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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