Клуб технических писателей

Хранение и учет документации

Екатерина
3 апреля 2015, 15:07

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

 

Хранение

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

Основные преимущества таких систем:

  • хранение всех версий одного и того же документа;
  • возможность возвращаться к более ранним версиям;
  • контроль всех изменений документа.

Для DITA-контента мы используем Subversion (SVN). Пользователи Windows работают с ней через Commandline SVN и TortoiseSVN. Маководы и линуксоиды используют стандартные пакеты своих операционок.


Хранение контента мы организовали по классической схеме.

В каждом репозитории есть две стандартные ветки:

  • trunk — здесь ведется разработка документации, создаются ее новые версии. Это рабочее поле технического писателя.
  • stable — сюда попадают согласованные версии документов из trunk. Никакие изменения в stable не допускаются.

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

 

 

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

Например:

  • файлы с текстами объединены в логические группы и лежат в отдельных каталогах или поименованы сходным образом;
  • иллюстрации к документам хранятся в подкаталоге image;
  • исходники иллюстраций, черновики текстов и прочие рабочие материалы — в каталоге work.

С такой структурой каталога документа понятно, где какие файлы искать.

 

 

Пробежимся еще раз — какой профит мы получаем от такой организации хранения:

1. Надежность:

  • система контроля версий;
  • выделенные репозитории;
  • физическое разделение разработческой и стабильной версий;
  • физическое разделение рабочих и публикуемых материалов.
2. Прозрачность:
  • единая структура репозиториев;
  • общие правила организации документов.

Учет

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

С одной стороны. Необходимо иметь всю информацию о документе: кто его писал, кто заказывал, когда была опубликована первая версия или последнее обновление.
С другой стороны. Хочется понимать, какие работы ведутся по документам в данный период времени (создание, актуализация, исправление ошибок, перевод, редактура).
С третьей. Нужно отслеживать загрузку людей по задачам.
 
 
Для учета своих задач мы используем багтрекер Яндекса, а вы можете использовать любой другой (например, JIRA, Pyrus).
 
 
Чтобы было проще ориентироваться в огромном пуле задач, для каждого типа документации (пользовательская справка, руководства разработчиков и внутренняя документация) выделен свой проект. Эти проекты, в свою очередь организованы одинаково.
Для каждого документа есть головная задача типа Task, в которой хранится основная информация о нем:
  • название;
  • ссылка на опубликованную версию;
  • место размещения исходников;
  • заказчик задачи;
  • консультанты.
Исполнителем задачи назначается техписатель, ответственный за этот документ. Все работы (создание, актуализация, исправление ошибок, доработки и пр.) фиксируются в виде подчиненных задач с типом Sub-task, у них тоже есть свои заказчики, консультанты и исполнитель.
Получается, что по типу Task мы всегда видим все документы, публикуемые на конкретном сервисе. Для каждого из них можно посмотреть историю и инициаторов всех изменений, даты публикации. Мы можем строить отчетность по задачам, выполненным конкретным автором или за определенный период. Таким образом, в любой момент можно отследить, что происходит с документацией и теми, кто ее пишет.

В заключение

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

5 комментариев
Подписаться на комментарии к посту

Спасибо, Екатерина!

ИМХО, идти по пути только пользовательского контента, думаю, не совсем целесообразно, так как "завтра" обязательно возникнет вопрос о хранении переписки, нормативной документации, разного рода проектных комплектов, типа, технических заданий, заданий на разработку, описаний структур и т. д.

Исходя из всего сказанного, если есть время :), попытаться решить вопрос как хранить "весь документооборот" компании, причем, учитывая, что одни документы сборочные - из топиков, скажем, созданных в DITA или DockBook, - а остальные цельные: MS Word, MS Excel и т. д.

Екатерина
8 апреля 2015, 17:04

SVN мы используем не только для пользовательской документации, но и для технической. Вообще, в SVN можно хранить абсолютно любые файлы — например, документы в MS Word, предназначенные для скачивания.

Что касается переписки и ТЗ, то их удобно прикреплять к задачам в багтрекере, т.к. фактически они относятся к определенному проекту, а разработка проекта учитывается с помощью задач.

Спасибо за ответ!

А историю до какого "уровня" храните? Например, у Вас есть 20 версий ТЗ с разбросом в 5 лет; все версии хранить будете, или "отрезаете" по определенную дату, скажем, - храним только за 3 последних года?

Екатерина
9 апреля 2015, 11:47

В SVN мы храним все версии документа. Даже если версий очень много — например, в месяц вносится 10-15 изменений в документ, и каждое изменение версионируется, — переполнения истории не происходит, и можно просмотреть даже самую первую версию документа.

 

Спасибо за проявленный интерес!

Действительно, интересно! Спасибо!