Методология документирования
В процессе документирования информационных систем и программного обеспечения мы ориентируемся на государственные стандарты (ГОСТ 34.ХХХ Комплекс стандартов на автоматизированные системы, ГОСТ 19.ХХХ Единая система программной документации, ГОСТ 2.XXX Единая система конструкторской документации и другие), а также на выработанные в отрасли лучшие практики и авторские методики.
Принципы разработки документации
Мы ставим перед собой цель, чтобы разрабатываемая нами документация удовлетворяла основным принципам:
- Принцип полноты. Описываем все альтернативы, все варианты поведения системы, все допустимые значения параметров и т. д.
- Принцип адресности. Следим за тем, чтобы пользователь получал из документации целевую для него информацию, соответствующую его бизнес-роли и квалификационному уровню.
- Принцип определенности. Стремимся минимизировать наличие двусмысленностей в тексте.
- Принцип экономии усилий пользователя. Ценим конечных пользователей нашей документации, поэтому прикладываем максимум усилий к тому, чтобы пользователи прикладывали минимум усилий для понимания материала.
- Принцип терминологической выдержанности и унификации. Используем принятую в IT терминологию, избегаем жаргонизмов. Ключевым моментом для нас является использование единого перечня терминов, принятого в начале документа.
На начальном этапе документирования решаем следующие вопросы:
- Выбираем подходящую технологию документирования. Мы используем как стандартные офисные приложения, так и технологии на базе единого источника, например, технологию DocBook/XML. Выбор определяется требованиями Заказчика, длительностью проектов и другими факторами.
- Определяем комплектность документации. Решаем, какие виды документов необходимо подготовить, исходя из предметной области системы, этапности проекта, архитектуры системы, состава бизнес-ролей пользователей и т.д.
- Разрабатываем требования к внутренней структуре документов. В зависимости от требований Заказчика выбираем тот или иной стандарт документирования, при необходимости используем авторские решения.
Мы подходим к документации не только как к составляющей выпускаемого продукта, но и как к произведению искусства!