И начать делать полезную документацию

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

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

1) Структурируйте информацию

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

1. Общее описание сети

2. ИТ-инфраструктура

• Сетевое оборудование
• Физические серверы
• Системы хранения
• Виртуальные машины
• Периферийные устройства
• Оргтехника
• …

3. ИТ-сервисы

• Доменные службы Active Directory
• Сервер обновлений WSUS
• Служба развертывания рабочих мест пользователей WDS.
• Почта
• Совместная работа с документами
• Телефонная связь
• Доступ в Интернет
• …

4. Приложение

• Лицензии на программное обеспечение
• Соглашение о наименовании
• …

2) Определите, для кого вы составляете документ

Описание ИТ-инфраструктуры – один документ, инструкция – другой. Не надо пытаться уместить в одном документе описание сервиса печати, инструкцию по предоставлению прав доступа к принтерам и по сканированию документов на МФУ. Лучше сделать 3 документа: описание ИТ-инфраструктуры, инструкцию специалиста техподдержки и инструкцию пользователя. В этом случае сисадмин, эникейщик и пользователь будут получать ровно ту информацию, которая им нужна, не перелистывая кучу страниц «лишней информации».

3) Добивайтесь полноты, целостности и единообразия данных

Если в документации у вас указывается какой-то технический параметр в описании устройства или сервера, то он должен быть указан для всех элементов, к которым применим, и, что не менее важно, везде в документации этот параметр должен называться одинаково. Если в дальнейшем в сети потребуется провести какие-то изменения (к примеру, изменить адрес сервера DNS), то простым поиском по документу можно будет составить полный список узлов, на которых потребуется также изменить настройки и тем самым точно спланировать проведение изменений. Вроде мелочь, а польза от документации возрастает в разы.

4) Избегайте дублирования информации

Чтобы изменения в ИТ-инфраструктуре можно было легко отражать в вашем документе в дальнейшем (и тем самым поддерживать его в актуальном состоянии) необходимо, чтобы информацию в нем приходилось менять только в одном месте. Т.е. значения параметров того или иного сервера, устройства или приложения должны быть указаны на весь документ один раз. Если вы в трех местах в документе указали, что у такого-то сервера настроен такой IP-адрес, то вполне вероятно, что через несколько лет в этом документе у сервера будет 3 разных IP-адреса и ваш документ потеряет свою первоначальную ценность. Только не спрашивайте меня, почему в таких случаях редко кто использует поиск по документу.

5) Не описывайте и не рекламируйте технологии, не используйте сравнительные обороты

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

6) Увеличивайте концентрацию смысла на единицу текста: используйте таблицы и списки

Самая худшая проектная документация, которую мне пришлось встречать, напоминала вступительное сочинение. Где-то к третьей странице у меня сливались воедино IP-адреса, маски, массивы, пользовательские сервисы и логины-пароли доступа. Чтобы найти нужный мне параметр в подобной документации приходилось читать несколько абзацев текста, надеясь, что в следующем предложении речь дойдет до нужного мне значения.
Старайтесь в документации использовать меньше не относящихся к теме слов. Полезно выносить все значимые величины в таблицы, а вместо перечисления делать списки – это позволяет, зачастую просто окинув взглядом раздел, сразу найти нужный параметр.

7) Один язык изложения и меньше булшита

Не «бекап», а «резервное копирование». Не «Antivirus», а «антивирусное ПО». Не «Hot Fixes» (изначальная стилистика сохранена), а «пакеты исправления». Вот вроде простые вещи, а документация перестает ломать мозг при прочтении.

8) Указывайте полные названия продуктов

Говорят ли вам сейчас о чем-то «Сервер SUS» или «Сервер RIS»? Прежде чем использовать в документации сокращенные названия какого-либо решения в качестве самодостаточного обозначения подумайте, будет ли оно о чем-то говорить техническим специалистам лет так через 5-10. К примеру, куда корректнее указывать данные решения как «сервер установки обновлений SUS (Software Update Services)» или «сервер сетевой установки операционных систем RIS (Remote Installation Server)».

9) Скриншоты дополняют, но не заменяют текстовую информацию

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

10) Используйте визуальные схемы и фотографии оборудования

Функциональная схема сети, расположение оборудования в стойке и как выглядит само оборудование – это не так сложно сделать и добавить в документ сейчас, зато значительно упрощает поиск нужной железки спустя 5-6 лет, когда не каждый админ сможет сказать, как выглядит сервер HP Proliant G8 2014 года выпуска.

11) Читайте написанную документацию внимательно. Проверяйте текст на ошибки!

Обороты вида «Централизованная печать пользователей в Московском офисе Заказчика осуществляется с использованием сервиса Network Printer» в исполнении лидеров рынка заставляет иной раз серьезно задуматься, так ли много я знаю о возможностях ИТ-технологий. Ну а об орфографических и пунктуационных ошибках я вообще молчу, хотя у меня у самого была тройка по русскому. Прежде чем отправить документ клиенту, внесите в него в разные места пару-тройку слов-закладок и дайте вычитать его человеку, более-менее понимающему в грамматике. Если он найдет все ваши закладки – работа сделана хорошо, но главное не перегибать с использованием нецензурных слов в закладках – иногда документация вместе с ними уезжает к клиентам.

Успехов!

Автор: ikormachev

Источник