Разработка документации на создаваемые ИТ-продукты – это не только «правила хорошего тона», но и насущная необходимость. Ведь без технического задания невозможно зафиксировать требования к продукту, без руководства пользователя сложно грамотно продуктом пользоваться, без технической документации, описывающей продукт, сложно будет искать и исправлять ошибки и проводить необходимые доработки, когда в них возникнет необходимость, и т.д.
Обычно документацию делают по одному из двух путей – либо используют стандарты, описывающие требования к составу, структуре и содержанию документов (например, ГОСТ 19-й и 34-й серий – ЕСПД и КСАС), либо самостоятельно разрабатывают документ, создавая его на основе собственного опыта или по существующим образцам, в т.ч. взятых из недр интернета. Конкретный вариант определяется, как правило, условиями контракта на создание ИТ-продуктов (а если продукт создаётся для собственных нужд, то только представлениями о важности и целесообразности документирования). Государственные заказчики, как правило, требуют документацию «по ГОСТ» (правда, трактовка требований иногда бывает достаточно странной), негосударственные же заказчики менее формально подходят к этому вопросу, зачастую совсем не требуя вместе с разработанным продуктом (программой, информационной системой) передавать документацию.
Тем не менее, лучше всё же документацию сделать, чем потом пожалеть о её отсутствии, если выяснится потребность в ней задним числом.
Но как же её сделать?
С документацией, разрабатываемой в соответствии с ГОСТ, вроде бы, всё понятно – состав документов ясен, требования к структуре и содержанию определены. Т.е. бери ГОСТ и пиши документ.
С документацией, разрабатываемой вне стандарта, сложней – хорошо, если найдётся образец похожего документа (в т.ч. иногда берут за основу аналогичные документы из ГОСТ), но хуже, если такого образца нет. Тогда, при разработке документации, нужно определить:
Назначение документа (для кого он предназначен, для каких целей, когда и при каких обстоятельствах может быть востребован и т.п.);
Состав и форму представления информации, которая должна быть включена в документ (исходя из назначения документа);
Структуру документа (тут важно не только правильно структурировать документ, выделив разделы и подразделы, но и сгруппировать информацию по логически обоснованным блокам).
А как потом из всего этого собрать документ? И как наполнить документ, структура которого «гостирована», т.е. описана в стандарте?
Лично я для себя взял за практику для любых документов делать синопсис.
Синопсис – краткое изложение содержания произведения (книги, документа, статьи и т.п.).
Независимо от того, «гостированный» ли это документ, или впервые разрабатываемый, я предварительно делаю синопсис, в котором выделяю несколько блоков:
Общее описание документа, в которое включаю описание назначения (целевая аудитория читателей, цели документа, общая характеристика включаемой в него информации и т.п.);
Примерную структуру (если документ стандартизованный, просто копирую структуру из стандарта; если документ нетиповой, то предполагаемый, исходя из логики и личного опыта, состав разделов как минимум верхнего уровня, состав подразделов и количество уровней вложенности, если их более 2 – но не более 5, чтобы документ не оказался слишком многоярусным, потому что такой просто будет неудобно читать);
Описание содержания каждого раздела/подраздела, в т.ч. состав и форму представления информации, источники сведений для наполнения раздела и т.п.
Третий пункт, как ни удивительно, особенно полезен при составлении стандартных документов. При всей, казалось бы, понятной и очевидной предопределённости содержания документов, предусмотренных стандартом, чёткое понимание того, что РЕАЛЬНО должно быть включено в данный раздел/подраздел, должно быть, но не всегда присутствует. Чаще всего проблемы возникают с определением источников информации, на основе которой должен заполняться раздел – прямое указание в синопсисе этих источников позволяет заранее понять, где брать информацию, либо, если на момент написания синопсиса ещё нет ясности с источниками, можно поставить указатель «Требуется уточнить» и написать примечание с предварительными отсылками к возможным источникам данных либо иной информацией, которая поможет раздел наполнить.
Если же документ нестандартный, то синопсис просто становится спасением. Причём очень хорошей практикой (я лично таким методом пользуюсь) является предварительное согласование (или хотя бы предоставление для ознакомления) синопсиса с заказчиком – это что-то наподобие MVP, но в документации: документа ещё нет, но заказчик видит, что у разработчика есть чёткое понимание, что в документе должно быть, а в ряде случаев на этапе синопсиса могут появиться и замечания, и пожелания от заказчика.
Синопсис можно делать как на отдельные документы, так и на весь предусмотренный проектом пакет. В таком случае я обычно делаю единый документ, в начале которого идёт перечень документов, разрабатываемых в рамках проекта, с указанием, на основе какого шаблона или стандарта они делаются, название, назначение, возможно – шифр документа и т.п.
Резюме. Синопсис для технической документации, составляемый перед её разработкой – вещь крайне полезная, упрощает и ускоряет разработку документации и снижает вероятность ошибок и пропусков. Рекомендую взять на вооружение.
