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

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

Хранение

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

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

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

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

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

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

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

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

 

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

Например:

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

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

 

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

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

• единая структура репозиториев;
• общие правила организации документов.

Учет

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

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

С другой стороны. Хочется понимать, какие работы ведутся по документам в данный период времени (создание, актуализация, исправление ошибок, перевод, редактура).

С третьей. Нужно отслеживать загрузку людей по задачам.

 

 

Для учета своих задач мы используем багтрекер Яндекса, а вы можете использовать любой другой (например, JIRA, Pyrus).

 

 

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

Для каждого документа есть головная задача типа Task, в которой хранится основная информация о нем:

• название;
• ссылка на опубликованную версию;
• место размещения исходников;
• заказчик задачи;
• консультанты.

Исполнителем задачи назначается техписатель, ответственный за этот документ. Все работы (создание, актуализация, исправление ошибок, доработки и пр.) фиксируются в виде подчиненных задач с типом Sub-task, у них тоже есть свои заказчики, консультанты и исполнитель.

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

В заключение

Еще раз перечислим то, что помогает нам делать хранение и учет документации более удобным:

• организация репозитория;
• система учета в багтрекере.

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

 Посмотреть видео доклада и презентацию