RTFM :: WYSIWYG Классификация

Источник: Hare.ru @ КБ

Читайте документацию: то что вы видите - это все, что у вас есть

Документирование - это традиционная головная боль любого творца. И, пожалуй, первым руководством пользователя стала Библия - книга, составленная различными людьми, не обновляемая уже две тысячи лет и написанная задним числом, как и всякая документация.

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

Цель данной статьи - вкратце сформулировать требования, состав и структуру документации на информационную систему (ИС) а также рассмотреть решения, удовлетворяющие данным требованиям применительно к платформам V7 и V8.

Исторически именно разработчики первыми озаботились документированием своих разработок. Результатом этих усилий по наведению порядка стали стандарты документирования, базирующиеся на исходных текстах программных модулей. Однако, с ростом масштаба и комплексности ИС, акценты в документировании все больше смещаются с кода в область формализации требований, архитектуры и регламента использования системы. Таким образом, все большее значение приобретают "производные" по отношению к коду документы.

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

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

Потребители информации	Документация на ИС
Потребители информации	Техническое задание	Программная документация	Руководство пользователя	Руководство по ведению учёта	Руководство по сопровождению
Разработчики	Что хочет получить клиент? Какие выдвинуты требования и ограничения со стороны Заказчика?	Какие объекты и для чего применяются в системе? Как все это собственно работает?
Внедрение	Какова последовательность внедрения системы, оптимальная для Заказчика? Какие наиболее важные функции системы должны быть внедрены в первую очередь? Как взаимосвязаны между собой эти функциональные подсистемы?
Пользователи			Что это у меня на экране и зачем оно вообще нужно?	Какое действие, когда и с каким объектом должен выполнить данный пользователь системы в рамках выполнения своих функционально-должностных обязанностей?
Сопровождение		Какие объекты и для чего применяются в системе? Как все это работает? Как бы мне тут кое-что поменять, чтобы при этом ничего не испортить?			Каким образом система перешла в текущее состояние? Какова алгоритмика обработки информации данным объектом ИС? (т.е. каким образом в системе был получен данный результат, и как его можно скорректировать?)

Рассмотрим эти элементы подробнее.

Категории потребителей информации об ИС сформированы по функциональному признаку. Названия категорий говорят сами за себя. Дополнительной расшифровки заслуживает, пожалуй, лишь категория "Сопровождение". Это специфическая категория потребителей информации об ИС, выполняющего следующие функции:

Оперативная поддержка пользователей ИС. То есть именно они будут объяснять пользователю "эту цифру в отчете" и "почему у меня не проводится этот документ".
Выполнение заявок пользователей на внесение текущих изменений в конфигурацию ИС и обновление связанной с внесенными изменениями документации ИС.

Документация информационной системы заслуживает более детального описания.

Техническое задание (ТЗ) является, по сути, иерархическим перечнем различных типов требований к информационной системе с указанием критериев оценки соответствия системы данному требованию.

Основу требований к ИС традиционно составляют:

Требования к составу и структуре функций системы, формализуемые в модели бизнес-функций Заказчика, поддерживаемых системой.
Требования к составу и структуре информационных объектов, используемых в ИС.

При этом я использую классическое функциональное проектирование ИС. Объектно-ориентированное проектирование здесь не рассматриваются прежде всего по из-за значительной сложности дальнейшей интерпретации полученной модели штатными средствами платформы 1C:V7/V8.

Степень детализации модели бизнес-функций определяется возможностью формирования на её основе Руководства по ведению учета для рабочих мест системы.

Кроме указанных выше к системе могут предъявляться самые разнообразные требования, однако в общем все они должны соответствовать т.н. SMART-критериям:

(S) Specific/конкретные
(M) Measurable/измеримые
(A) Achievable/достижимые
(R) Realistic/разумные
(T) Time-Based/четко привязанные ко времени

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

Программная документация, неотъемлемо связанная и интегрированная в конфигурацию (структуру, формы, модули) ИС. Данная информация объективно является наиболее детальным и актуальным описанием собственно ИС и предназначена для программистов, непосредственно вносящих изменения в структуру, формы и программные модули ИС.

Руководство пользователя представляет собой описание объектов системы, с которыми взаимодействуют пользователи ИС, и включает в себя:

Краткое описание назначения информационного объекта.
Руководство по использованию экранной формы объекта ИС.

Руководство по ведению учета формируется в виде инструкции для рабочего места системы и содержит последовательность действий с объектами системы, которые пользователь должен выполнять в ИС в рамках своих должностных обязанностей. Данное руководство строится на основе модели бизнес-функций предприятия, содержащейся в ТЗ. Именно для обеспечения согласованной модели бизнеса и настраивается информационная система.

Руководство по сопровождению содержит в себе сводную алгоритмику обработки информации информационными объектами ИС. Появление данного документа при наличии исчерпывающе полной Программной документации требует дополнительного пояснения. Дело в том, что Программная документация при всей своей полноте не вполне соответствует потребностям Сопровождения, заключающимся прежде всего в быстром определении сути проблемы. Используя закон Парето (принцип 80/20) можно сказать, что для решения 80% проблем, связанных с эксплуатацией системы достаточно изучить 20% информации о механизмах её работы.

Именно это соображение и примиряет меня с необходимостью поддержания в актуальном состоянии Руководства по сопровождению, являющегося, по сути, дополнительным разрезом в документировании системы.

Итак, мы определили потребителей, их потребности в информации о нашей информационной системе и сформулировали состав документации к ней. Дальше речь пойдет о том, как заставить все это работать применительно к платформе V7/V8.

Продолжение следует