Проверка / нормоконтроль проектной ИТ документации

Введение

Обычно разработке документации уделяется время по остаточному принципу. Программисты — люди думающие, умеют работать при недостатке документации и самостоятельно восстанавливать пропущенную информацию. Поэтому, они считают, что другие так же смогут работать в таких условиях. К сожалению, это не так.

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

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

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

Контроль документов в ДИТ

Критерии прохождения

По каждому проверяемому документу дается заключение с перечнем замечаний или вопросов. Если список претензий пустой, то заключение положительное.

Общее заключение по документу состоит из перечисленных в таблице ниже критериев. По каждому пункту выдается заключение о соответствии: соответствует или не соответствует документ критерию и пишется набор замечаний.

№	Критерий	Комментарии
1.	Прослеживаемость функциональных и нефункциональных требований от постановки задачи до контроля результатов	Легко выполнимый критерий. Заголовки пунктов функциональных и нефункциональных требований частных технических заданий должны соответствовать основному техническому заданию, по которому и ведется проверка. Аналогично, заголовки пунктов в документах технического проекта, руководств пользователей и программы и методики испытаний и других документов должны соответствовать друг другу и техническому заданию
2.	Непротиворечивость отдельных документов друг другу	Легко выполнимый критерий. Одинаковые требования лучше включить в общий шаблон и продублировать во всех документах
3.	Полнота и необходимый уровень детализации	Проверка проходит с замечаниями. Раскрыты ниже …
4.	Соответствие техническим и технологическим требованиям, заявленным в ТЗ	Проверка проходит с замечаниями. Раскрыты ниже …
5.	Соответствие требованиям ДИТ (шаблоны, типовые вставки, нормативные документы)	Проверка проходит с замечаниями. Раскрыты ниже …
6.	Корректные структура и содержание, соответствие государственным и отраслевым стандартам	Проверка проходит с замечаниями. Раскрыты ниже …
7.	Корректная терминология	Легко выполнимый критерий. Читают документы в основном неспециалисты и термины они не знают. Следует только все обозначения и сокращения включить в раздел «Перечень обозначений, определений и сокращений»
8.	Форматно-логическая корректность, корректность изложения	Замечаний у меня не было от слова «совсем». Но, наверное, нужно просто писать на нормальном русском языке
9.	Соответствие правилам орфографии и пунктуации русского языка	Не показывается в таблице критериев, но активно используется. Проверка проходит с замечаниями. Трудно закрыть, так как при обнаружении даже одной ошибки дается замечание «Проверить пунктуацию (или орфографию) по всему документу» и документ возвращается на доработку

Полнота и необходимый уровень детализации

Каждый следующий документ в цепочке проектных документов должен постепенно детализировать и раскрывать механизм реализации исходных требований. Все требования из ТЗ должны быть повторены в явном виде в ЧТЗ. Если требование убирается или включается в другое, то надо именно эту формулировку и написать «требование пункта ТЗ 4.2.4 убрано по следующим соображениям …«. Иначе потом придется давать пояснение, почему требование убрано. Лучше это делать в тексте сразу.

Примеры замечаний:

1. Раздел 4. Согласно ТЗ, некоторые требования должны быть детализированы в ЧТЗ (р.4.1, 4.3). Необходимо доработать – нефункциональные требования из основного ТЗ желательно дополнить описанием механизма реализации требований. Обязательно, если делается ссылка на следующий этап работ, то следует указать, в каком документе будут уточнены или раскрыты требования к Системе (Модулю). См. примеры ниже.

2. Аналогичный пример: Раздел 7.5. Необходимо указать как, когда и где должна быть проведена подготовка персонала для работы с Модулем – аналогичные исправления, переделано в следующий текст: «Подготовка персонала для работы с Модулем должна быть проведена в соответствии с календарным планом (приложение 2 к Государственному контракту)».
3. Раздел 4.1.5. Необходимо привести детальные требования к диагностированию Системы и реакции на отклонения заданных параметров, согласно требованиям ТЗ – хотя достаточно сложно понять без проектирования как можно диагностировать Систему, следует дополнить какими-нибудь параметрами все разделы, чтобы не было повторения основного ТЗ.
4. Если требования должны быть уточнены далее по ходу проекта, то следует четко указать на каком этапе или в ходе каких работ и обязательно привести название документа, где они будут расписаны. См. пример ниже.

5. Раздел 4.2.1. Необходимо использовать как минимум все атрибуты, согласно требованию ТЗ, для возможности формирования сообщения о факте нарушения. Данное замечание появляется, если в ЧТЗ по каким-то причинам был сокращен состав предоставляемой информации. Мы дали ответ: «Согласно пункту 4.2.2 ТЗ состав передаваемых и получаемых атрибутивных данных должен быть уточнен на этапе разработки ЧТЗ и определен с учетом соблюдения норм Конституции Российской Федерации и положений действующего законодательства Российской Федерации. Согласно пункту 4.2.2 ТЗ, НПА, приведенным в разделе 9 ЧТЗ, и в частности федеральному закону от 27.06.2006 № 152-ФЗ «О персональных данных» сервис должен предоставлять только деперсонифицированную информацию. Согласно выше сказанному, а также для предотвращения избыточности отображаемой информации, часть атрибутов, прописанных в ТЗ, была исключена для отображения пользователю» и замечание (все подобные замечания) было снято.

Соответствие техническим и технологическим требованиям, заявленным в ТЗ

Частные технические задания должны содержать требования, уточняющие и детализирующие требования основного ТЗ. Если по каким-то соображениям требования в ЧТЗ меняются или снимаются, следует прямо в тексте написать, на основании чего это делается.

Примеры замечаний:

1. Необходимо привести детальные требования по всем подразделам раздела 4, в соответствии с требованиям ТЗ. Замечание связано с тем, что по тексту ТЗ следует в частных технических заданиях раскрывать более подробно все требования. Хотя это не всегда рационально (бывает, что требования в ТЗ достаточно подробно и правильно описаны), приходится выдумывать и дописывать текст по многим пунктам разделов 4.1 и 4.2 ЧТЗ.
2. Раздел 4.1.9.2. Система должна предоставлять возможность корректного автоматического завершения работы при прекращении подачи питания на срок, превышающий возможности источников бесперебойного питания. Так же необходимо уточнить возможности систем резервного питания. Требование было убрано в ЧТЗ, так как добавили другое, более сильное. Но пришлось давать комментарий в листе регистрации исправлений. Лучше в ЧТЗ привести требование из основного ТЗ и написать почему его не следует реализовывать.
3. Раздел 4.3.7. Необходимо указать каким образом и в каком случае оказываются консультационные услуги пользователям. Аналогично замечанию 1 из пункта 1.1.2. Исправлено на: «Исполнитель должен обеспечивать оказание пользователям консультационных услуг по программному обеспечению модуля «Свойства документа — Тема» по телефону и/или электронной почте по вопросам, связанным с функционированием Модуля, и описанным в документах «Руководство пользователя» и «Руководство системного программиста (администратора) Модуля»».

Соответствие требованиям ДИТ

Наибольшее количество замечаний приводится по данному критерию. Следует уделить пристальное внимание следующим моментам:

• все определения и сокращения, используемые в тексте документа, должны быть отражены в разделе «Перечень обозначений, определений и сокращений». Лучше всего перечень наполнять в процессе написания документа (добавлять туда все, что попадется), а в конце пройтись по перечню и убрать лишнее;
• необходимо указывать в каком документе должны отражаться уточненные количественные показатели масштабируемости (требование – аналогичное замечанию 1 из пункта 1.1.2). Если что-то должно быть уточнено или определено позднее, следует указать этап работ и документ, в котором это будет описано;
• так как больше количество требований копируется из ТЗ и других документов (примеров других проектов), то необходимо переформулировать требования, заменив слова «обеспечивает» на «должен». Следует применять соответствующие конструкции:
  • в ТЗ и ЧТЗ – Система «должна выполнять», «должна содержать», «должна обеспечивать». Никаких повествовательных форм в ТЗ и ЧТЗ;
  • наоборот, в документах технического проекта (пояснительной записке, описании информационного обеспечения и т.п.) следует применять повествовательные (описательные) конструкции предложений: «выполняет», «содержит», «функционирует» и т.п.;
• на все таблицы, рисунки и приложения должны быть ссылки в тексте самого документа. Если приводится таблица или рисунок значит, они что-то поясняют, раскрывают. Следует в тексте добавить подобную фразу « … приведено в таблице ниже (Таблица 2)»;
• необходимо проконтролировать наличие раздела вроде «Источники разработки», и отразить в нем всю используемую литературу и документацию.

Примеры замечаний:

1. Необходимо оформить Лист утверждения – вообще-то данное замечание некорректно формулируется отделом нормоконтроля, так как по ГОСТ делается либо титульный лист с подписями и без листа согласования, либо титульный без подписей, но с листом согласования. Но раз «гаврики» хотят, то нехай будет лист согласования. Важно! Лист согласования не включается в общую нумерацию листов документа (титульный лист – включается);
2. Раздел 4.1.8.2. Сокращение «мин.» в данном случае в тексте документа не допустимо, необходимо использовать полное слово – как мы поняли, сокращения вообще по минимуму использовать, за исключением сокращений длинных названий систем, органов власти или технических терминов (БД, ОС, SAA и т.д.);
3. Раздел 7.5. Необходимо указать как, когда и где должна быть проведена подготовка персонала для работы с Модулем – замечание аналогичное замечанию 1 из пункта 1.1.2;
4. Раздел 3.4.2. Необходимо добавить авторизацию на все сервисы Системы, или описать причину, по которой к другим сервисам доступа нет. Если происходит сокращение функционала (в нашем случае он разделен на 2 этапа), то следует прямо в тексте документа написать, почему есть отличия от основного ТЗ (например, реализация данного требования запланирована на 3 этапе работы);
5. Раздел 5.3.2. Необходимо привести процедуры контроля БД – было краткое описание, сделали более подробное.

Корректные структура и содержание, соответствие государственным и отраслевым стандартам

Следует перечитать ГОСТ на соответствующий разрабатываемый документ и обратить внимание на то, что должно быть написано в разделах документа. Все требования должны быть подробно расписаны.

Примеры замечаний:

1. Раздел 2.2. Необходимо указать критерии оценки достижения целей.
   1. Было: «Целью разработки модуля «Свойства документа — Тема» является создание интерактивного интерфейса между УГИБДД и жителями г. Москвы для получения от них сведений о фактах нарушений в организации безопасности дорожного движения и нарушении правил дорожного движения»;
   2. Переписано следующим образом: «Целью разработки модуля «Автохам» является создание интерактивного интерфейса между УГИБДД и жителями г. Москвы для получения от них сведений о фактах нарушений в организации безопасности дорожного движения и нарушении правил дорожного движения.      
      Критериями достижения целей создания модуля «Автохам» являются автоматизация процесса получения сведений от пользователей о фактах нарушений в организации безопасности дорожного движения и нарушении правил дорожного движения и достижение показателей назначения Модуля, приведенных в разделе 4.1.8.»;
2. Раздел 4.2.1. Необходимо заполнить столбец таблицы, иначе непонятно для чего он. Что обозначает максимальная длина? – заполняем пустые столбцы и подробно описываем заголовки.

Рекомендации оформлению документов в MS WORD

Использование шаблонов

Для единообразного оформления документов предлагается использовать механизм шаблонов MS Word. Это позволяет избежать множества проблем при подготовке и приемке документации.

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

В качестве шаблона нужно подготовить документ, в котором настроить и закрепить (заблокировать от изменений) набор стилей, и сохранить его в формате шаблона. Можно сделать как один шаблон для всех вариантов, так и отдельные шаблоны для каждого вида документа: техническое задание, частное техническое задание, пояснительная записка и так далее. Для правильной работы со стилями необходимо:

• использовать только встроенный набор стилей MS Word:
  • для заголовков использовать стили «Заголовок 1», «Заголовок 2» и так далее;
  • для основного текста абзацев – стиль «Обычный»;
  • для списков – маркированные и нумерованные списки;
  • для рисунков и таблиц – стили соответствующих блоков;
  • для оглавления — стили оглавления;
• настроить выбранные стили так как вам необходимо:
  • задать вид и размеры шрифта;
  • задать отступы и интервалы;
• заблокировать от изменений данные стили;
• запретить форматирование в документе другими стилями.

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

Набора из 20-30 стилей должно хватать для подготовки практически любых документов, но бывают случаи, когда надо изменить или добавить немного новых сталей. Тогда надо снять блокировку. Вызываем окно управления стилями, нажимая соответствующую кнопку.

И убираем блокировку стилей, для этого снимаем флажок «Ограничить форматирование разрешенными стилями», смотри на рисунке ниже.

На блокировку ставится пароль. Рекомендуется после внесения изменений вернуть блокировку обратно, чтобы не портить дальнейшее оформление текста.
Зеленым подчеркнут флажок, который надо обязательно устанавливать при блокировке стилей: когда он установлен, кавычки гусиные лапки “” меняются автоматически на «».

Рекомендации по оформлению текста

Заголовки

Заголовок 1 уровня должен быть заглавными (прописными) буквами и текст выровнен посередине абзаца (для документов 19 серии ГОСТ), для 34 серии ГОСТ, заголовок 1 уровня использует строчные буквы и выравнивание влево с абзацным отступом (обычно 1,5 см.).

Отступ у заголовков 2, 3 и более уровней должен быть равен отступу 1-ой строки абзаца (обычно 1,5 см.), выравнивание слева.

Ссылки на разделы и пункты документа должны быть ссылками

Текст абзацев

Междустрочный интервал 1,5, размер шрифта 14, отступ 0 см, первая строка 1,5 см., обычно используется шрифт «Times New Roman».

Для текста настроен основной стиль «Обычный», на котором основаны все остальные, если посмотреть в окно «Свойства стиля» (надо снять блокировку), то можно увидеть, что все стили настраиваются как дельта от «Обычного» (Рисунок ниже).

Когда вы выбираете пункт «Очистить все» в списке стилей или нажимаете кнопку «Очистить формат», как показано на рисунке ниже, то оформление выделенного текста возвращается к стилю «Обычный».

Для выделения (если очень необходимо) отдельных слов или фраз следует использовать стили Строгий и Слабое выделение. Это стили не абзаца, а шрифта (выбранных нескольких слов).

Таблицы и рисунки

Для таблиц в шаблоне желательно настроить следующие 4 стиля (см. далее).

Текст таблицы – текст в ячейках таблиц, без абзацного отступа, чтобы занимать всю ячейку

— Текст таблицы – маркированный список – для оформления списков в таблицах (с небольшим отступом)

Текст таблицы заголовок – для задания заголовков

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

Для показа рамки в стилях шаблона предлагается оставить единственный вариант, приведенный на рисунке ниже (Рисунок 6).

Для вставки рисунков должны быть настроены два стиля:

• Рисунок по центру – задано центрирование и «не отрывать от следующего абзаца» (названия);
• Название рисунка – задано центрирование и отсутствие отступа перед абзацем, чтобы название располагалось как можно ближе к рисунку.

Важно:
— в подписи рисунков не должно быть точки;
— на все рисунки и таблицы должны быть ссылки (именно ссылки) в документе (перекрёстная ссылка MS WORD) — не должно быть рисунков и таблиц, которые не упоминаются в тексте документа.

Списки

Для оформления списков должны быть настроены варианты маркированных и нумерованных списков (см. рисунок). Вообще, по ГОСТ надо использовать определенную последовательность маркеров вложенных списков, но на практике к этому редко придираются.

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

При задании нового нумерованного списка может слететь оформление 1-го абзаца – надо снять блокировку и исправить оформление вручную.

Сокращения и обозначения

Все сокращения и обозначения должны быть описаны в списке сокращений, в начале документа, раздел «Обозначения и сокращения». Желательно сокращения простых слов и единиц меры не использовать, например: «год», а не «г.», «город», а не «г.».

Сжатие/несжатие рисунков в документах MS Office

Приложения MS Office по умолчанию сжимают рисунки при вставке их в документ. Требуется установить в «Параметрах» (Файл -> Параметры -> Дополнительно -> Размер и качество изображения) соответствующую галочку, чтобы этого не происходило (этот пункт есть для всех «офисных» программ – PowerPoint, Word и т.д.). См. рисунок ниже.

Рекомендации по написанию текста

Вообще то, орфографию и пунктуацию должен поправить ваш внутренний нормоконтроль или технический писатель :-). Но по факту, из-за большой загрузки не всегда можно это сделать. Так что надо писать правильно сразу:

• элементы маркированных списков заканчиваются точкой с запятой (как здесь);
• элементы нумерованных списков заканчиваются точкой;
• в конце текста в ячейках таблиц не надо ставить точку, хотя предложения разделяются точками, однозначно;
• в конце маркированного списка надо ставить точку (вот).