Документация для начальника

Преамбула

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

Область применения

Разумеется, в разных ситуациях и разным людям нужна разная документация. Пользователю системы необходимо знать, какие кнопочки нажимать, администратора интересуют настройки, а программиста программные модули. Однако эти виды документации объединяет одно общее свойство – они все несут какую-то полезную информацию, являющуюся руководством к действию читателя. А теперь самое интересное – представьте, что это свойство отсутствует. Если представить удалось, то, скорее всего, возник законный вопрос «а нафига это нужно?». Рассмотрим типичную ситуацию. Вы разработчик и у вас есть заказ на определенную систему. Вы обговорили с заказчиком условия, сроки и составили ТЗ на пару страничек А4. Все хорошо, работа кипит, появились первые наброски. И тут ваш заказчик сообщает, что деньги вам будут идти по безналу через центральный офис, а значит проект должен быть одобрен «большим босом», который, в свою очередь, тоже перед кем-то там должен отчитаться. При этом, ваш клиент заверяет, что все это лишь бюрократическая формальность, что неофициально согласие получено и что все будет хорошо. Но! Для оформления всех этих формальностей нужна полная детализированная документация. Так вот, именно такая ситуация и является тем самым случаем, когда документация не будет являться руководством к действия. Фактически, она нужна для того, что бы показать на вопрос «куда пошли деньги?». При этом, документация должна выглядеть внушительно (как минимум содержать много страниц текста), что бы ни у кого не возникло сомнений, что работа проделана колоссальная. Будут ли ее читать? Если деньги не большие, то, скорее всего, не будут. Но, если кого-то из начальства станет «мучить жаба», то для успокоения совести, босс может пролистать ваше творчество и прочитать несколько наугад взятых абзацев. Если «жаба» будет свирепствовать, то может поручить чтение кому-то. Так что писать откровенный бред нельзя – можно «влететь» в неприятности. Тут, как говорится, «надейся на лучшее, а рассчитывай на худшее». Так что писать все-таки придется. Но, что же писать, когда информация, которой вы владеете – это пара страниц ТЗ и ваши технические наработки, про которые писать совсем не хотелось бы – это создаст вам дополнительные ограничения (придется соответствовать тому, что написали).

Как писать документацию для «большого босса»

Хорошее название – залог успеха

Возможно, вы уже придумали название для вашего проекта. Возможно, оно даже получилось красивым, элегантным и достаточно кратким (в одно-два слова). Это все замечательно, но сейчас нам понадобится длинное и емкое название. Попробуйте охарактеризовать свою систему в двух-трех предложениях. Получилось? А теперь объедините эти предложения в одно сложное и разбавьте парой-тройкой «умных» ничего незначащих слов общего характера. К примеру, вы пишете электронный магазин, и ваша характеристика получилась примерно следующей:

База данных товаров бытового назначения. Набор сервисов для синхронизации с филиалами заказчика. Web-интерфейс (сайт) для конечных пользователей.

Составим из этого «хорошее» название:

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

Есть – название готово. В дальнейшем вы может написать, что это полное название вашей системы и что есть еще краткое, которое вы будете использовать в дальнейшем. Но! Не делайте этого сразу. Сначала, ваше полное название должно быть использовано в вашем введении (а, может быть, и не только во введении) – это позволит вам получить приличный объем текста из ничего. А теперь посмотрим на реальный пример, который использовала компания «Ростелеком». Название системы:

ПЕРВАЯ ОЧЕРЕДЬ системы ведения расписания приемов специалистов, проведения консультаций, в том числе телемедицинских, и загрузки мощностей медицинской организации, а также электронной записи на прием к врачу, с учетом возможности интеграции с внешними информационными системами с использованием облачных технологий

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

Техническое задание на выполнение работ по созданию первой очереди системы ведения расписания приемов специалистов, проведения консультаций, в том числе телемедицинских, и загрузки мощностей медицинской организации, а также электронной записи на прием к врачу, с учетом возможности интеграции с внешними информационными системами с использованием облачных технологий, содержащееся в приложении 1 к государственному контракту Министерства здравоохранения и социального развития Российской Федерации и ОАО междугородной и международной электрической связи «Ростелеком» на выполнение работ по созданию первой очереди системы ведения расписания приемов специалистов, проведения консультаций, в том числе телемедицинских, и загрузки мощностей медицинской организации, а также электронной записи на прием к врачу, с учетом возможности интеграции с внешними информационными системами с использованием облачных технологий от 13.02.2012 № К-29-Т/14-1.

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

Масло масленое

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

Отсутствием JOIN-ов и многодокументных транзакций достигается высокая производительность работы и простая масштабируемость.

Высокая производительность MongoDB достигается за счёт отсутствия JOIN-ов и встраивания, что делает чтение и запись быстрыми;

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

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

Маленькая девочка, увидев дождевого червя, спросила у старшего брата

– Кто это? – Брат посмотрел и так многозначительно отвечает

– Это кто-то куда-то ползет

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

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

Безопасность информации Системы обеспечивается за счёт согласованного применения технологических, организационных, технических и программных мер и средств защиты на всех этапах подготовки, обработки, передачи и хранения информации.

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

В доме, который построил Джек

Еще одним отличным примером нагромождения, является прием объединения предложений с помощью вводных слов «который», «в случае», «наряду с», «используемом для» и т.д. Отличным примером этого подхода является детский стишок «Дом, который построил Джек». А вот и реальный пример, способный вогнать в хороший транс даже бывалого читателя:

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

Несколько слов об использовании аббревиатур

Слишком частое использование аббревиатур не имеет смысла, так как сделает ваш документ меньше. Однако, при грамотном подходе, из этого инструмента тоже можно извлечь пользу. Подготовьте табличку «используемые термины», в которой поместите пару десятков малоизвестных аббревиатур с расшифровками (широко распространенные сокращения лучше не использовать вообще – в этом нет никакого смысла). Эту табличку нужно поместить куда-нибудь в середине документа (в начале или конце ее слишком легко найти). После этого, в разных местах документа периодически вставляйте сокращения из этой таблицы.

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

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

Обоснование использования

Зачастую сами начальники просят обосновать использование того или иного инструмента. Так что раздел, озаглавленный, как «Обоснование использования системного и программного инструментария» вызовет только одобрение. А, при правильном подходе, им можно заполнить не один десяток страниц, параллельно обезопасив себя на будущее от целого ряда вопросов. К примеру, вы пишите клиентское приложение и вам совершенно не хочется портировать его на мобильные устройства. Отлично! Пишем обоснование использования монитора:

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

Не хотите оптимизировать программу под древние машины – не вопрос. Пишите обоснование четырехядерного процессора. Кроме того, обоснование некоторых узлов может быть написано и просто так – для увеличения объема и для того, что бы завуалировать реально полезные обоснования. Реальный пример:

В качестве основного носителя информации (данных) выбраны накопители на жёстких магнитных дисках (НЖМД), организованные в дисковые массивы по технологии RAID.

Выбор обоснован следующими критериями:

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

Картинки и диаграммы

Обязательно добавьте в документацию несколько диаграмм общего вида. Много добавлять не нужно – это создаст впечатление несерьезности документа. Однако, 1-2 диаграммы на каждые 100 страниц – это хорошо и создает ощущение проработанности. Вполне возможно, что принимающий человек посмотрит только картинки. Ваши диаграммы должны быть красочными, понятными и, конечно же, они не должны содержать никакой ценной информации. Специально для этой статьи я нарисовал небольшую диаграмму, которая подойдет для любой системы, построенной по модели «клиент-сервер».

Заключение

Используя предложенные подходы, вы легко напишете документацию ровно на столько страниц, на сколько захочет ваш заказчик. При этом весь ее смысл останется на тех двух страницах ТЗ, которые были у вас изначально. А, по мере тренировки своих навыков, вы сможете писать «хорошо проработанную документацию» даже до того, как познакомитесь с заказчиком и узнаете, что он хочет.