Ключевые потребители документации решения:
- Пользователи решения;
- Сотрудники поддержки, которые помогают пользователям работать с решением;
- Администраторы, которые обеспечивают его доступность;
- Разработчики, которые его создали и развивают.
У каждого потребителя документации свои запросы. Например:
- Пользователям решения важно понять, как им взаимодействовать с системой. При этом важно помнить, что под пользователями скрываются сотрудники разных ролей. Для каждой роли необходима своя документация;
- Сотрудникам поддержки решения важно быстро ориентироваться при обращении пользователей и уметь вносить изменения в само решение или в данные в нем;
- Администраторам решения нужно контролировать работоспособность и уметь её восстанавливать в случае внештатных ситуаций;
- Разработчикам необходимо сохранить знания о решении и избежать потери информации при уходе одного из участников команды.
Кроме этого, при документировании решения необходимо опираться на уровень пользователей, которые будут с ним работать. Например, решение для пользователей с низким уровнем компьютерной грамотности, потребует описания детальных пошаговых инструкций.
На основании потребителей и их особенностей можно сформировать необходимый перечень документов для решения.
Бывает так, что документацию начинают писать в самом конце, когда решение уже разработано и готовится к запуску в production-среде. Такой подход может создать не мало проблем ещё в процессе разработки. Например, если один из участников команды заболеет или уволится, важная информация о решении может быть упущена. Поэтому рекомендуется своевременно формировать и обновлять документацию, чтобы она не устаревала. Чем больше времени проходит от изменения до документирования — тем больше трудозатрат потребуется на актуализацию.
Перечень документов, которые могут быть сформированы по решению:
- Краткое описание решения: для чего оно и какие задачи решает. Такое описание поможет любому потребителю быстро понять суть решения;
- Настройка решения: как правильно настроить решение в начале и на что влияют эти настройки;
- Описание инфраструктуры: какие мощности используются для решения, как контролировать его доступность и обслуживать сервера;
- Инструкции по ролям — описание интерфейсов и сценариев взаимодействия с решением для каждой роли;
- Архитектура решения:
a. Состав решения — что в себя включает решение;
b. Взаимодействие элементов решения — как они взаимодействуют между собой;
c. Возможности расширения решения — как правильно использовать заложенные возможности расширения и дорабатывать функциональность.
