Как справиться с управлением версиями документации программного обеспечения и самого программного обеспечения? [закрытый]

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

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

Что касается создания документации для каждой сборки программного обеспечения, спросите себя: действительно ли это имеет смысл? Документация историческая или предписывающая? Любая документация, которая создается с каждой сборкой, лучше имеет инструменты для этого. В настоящее время это работает только для документации API, и для его поддержки есть инструменты в стиле Doxygen / Javadoc. Скорее всего, это никогда не будет выполнено для руководств пользователя и руководств по установке, потому что они зависят от контекста.

Потребность в различных системах контроля версий сохраняется, в частности, в новых методологиях структурированной документации. Структурированная документация должна управляться на гораздо более высоком уровне детализации, чем исходный код, чтобы иметь возможность эффективно обрабатывать что-то даже такое, казалось бы, простое, как ребрендинг; обычно выполняется на уровне абзаца, предложения или слова, в отличие от уровня файла, которого достаточно для исходного кода.Кроме того, обычно экономически выгодно разделять элементы документа между несколькими продуктами или отделами (инжиниринг, маркетинг и т. Д.). И для такого уровня сложности документации достаточно только системы управления контентом для отслеживания контента и управления изменениями; SCCS в стиле CVS- / SVN- / Perforce- / Clearcase совершенно неадекватны для управления реальной документацией. Использование разных инструментов управления версиями обеспечивает разные номера версий для документации и программного обеспечения.

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

Разделение процессов документации и разработки уменьшает зависимости, что является основным показателем, необходимым для производства качественного продукта. Кроме того, желательно позднее связывание, чтобы наилучшим образом приспособиться к быстрой скорости изменений и непредсказуемым событиям, таким как позднее добавление или удаление функций. Только в момент финального (или альфа- / бета-выпуска) версия документации должна быть сопоставлена ​​с версией программного обеспечения. Но я согласен с High-Performance Mark, что конечный пользователь не должен видеть разные номера версий. Номер версии документации не обязательно указывать в документе. Этот номер можно сохранить в процессе документирования и скрыть от общественности.

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

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

Что касается синхронизации номеров версий кода и документации, мы предпочитаем, чтобы версия 1.1.1 документа соответствовала версии 1.1.1 программного обеспечения, 3.2.45 соответствовала 3.2.45 и так далее. Однако на практике у нас часто есть документация только для первых двух цифр (например, 1.1, 3.2), поскольку третья цифра предназначена в основном для исправления ошибок или повышения производительности. Номер версии репо вставляется в документацию (и в исходный код) с помощью ключевых слов svn: на случай, если он нам когда-нибудь понадобится.

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

Почему бы вам просто не использовать контроль версий и не использовать его как автоматическую редакцию документа? Вы можете попросить большинство систем обновить текст при оформлении заказа.

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

Системная документация для productX 1.3

Ревизия документации 1.7

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