Качество > Методология > Методология документирования

Методология документирования

В процессе документирования информационных систем и программного обеспечения мы ориентируемся на государственные стандарты (ГОСТ 34.ХХХ Комплекс стандартов на автоматизированные системы, ГОСТ 19.ХХХ Единая система программной документации, ГОСТ 2.XXX Единая система конструкторской документации и другие), а также на выработанные в отрасли лучшие практики и авторские методики.

Принципы разработки документации

Мы ставим перед собой цель, чтобы разрабатываемая нами документация удовлетворяла основным принципам:

  • Принцип полноты. Описываем все альтернативы, все варианты поведения системы, все допустимые значения параметров и т. д.
  • Принцип адресности. Следим за тем, чтобы пользователь получал из документации целевую для него информацию, соответствующую его бизнес-роли и квалификационному уровню.
  • Принцип определенности. Стремимся минимизировать наличие двусмысленностей в тексте.
  • Принцип экономии усилий пользователя. Ценим конечных пользователей нашей документации, поэтому прикладываем максимум усилий к тому, чтобы пользователи прикладывали минимум усилий для понимания материала.
  • Принцип терминологической выдержанности и унификации. Используем принятую в IT терминологию, избегаем жаргонизмов. Ключевым моментом для нас является использование единого перечня терминов, принятого в начале документа.

На начальном этапе документирования решаем следующие вопросы:

  • Выбираем подходящую технологию документирования. Мы используем как стандартные офисные приложения, так и технологии на базе единого источника, например, технологию DocBook/XML. Выбор определяется требованиями Заказчика, длительностью проектов и другими факторами.
  • Определяем комплектность документации. Решаем, какие виды документов необходимо подготовить, исходя из предметной области системы, этапности проекта, архитектуры системы, состава бизнес-ролей пользователей и т.д.
  • Разрабатываем требования к внутренней структуре документов. В зависимости от требований Заказчика выбираем тот или иной стандарт документирования, при необходимости используем авторские решения.

Мы подходим к документации не только как к составляющей выпускаемого продукта, но и как к произведению искусства!