Як перестати робити виконавчу проектну документацію

І почати робити корисну документацію



Переважна більшість проектів з побудови ІТ-інфраструктури, реалізованих навіть дуже великими системними інтеграторами, володіє одним істотним недоліком — марною проектною документацією. Ні, ні, звичайно ж, документація містить всі необхідні дані і, прочитавши її можна розібратися, що і як було організовано. Марність її проявляється при подальшій експлуатації інформаційних систем і виражається в складності підтримки документації в актуальному стані і неможливості оперативно знайти в ній потрібну інформацію. Як наслідок, ця проектна документація, з часом, замість корисного довідкового матеріалу стає ще одним красивим і марним звітним документом.

У даній статті я б хотів поділитися з моїми колегами деякими принципами складання проектної документації, які ми використовуємо у своїй роботі і які, можливо, дозволять вашим клієнтам насолоджуватися не тільки якісно побудованої вами ІТ-інфраструктурою, але і легко і невимушено підтримувати в актуальному вигляді документацію по ній, роками згадуючи вас добрим словом. Приступимо:

1) Структуруйте інформацію
Ваш документ буде прочитаний повністю, швидше за все, тільки на етапі здачі проекту. Чи будуть до нього звертатися надалі, залежить від здатності документа давати швидкі відповіді на короткі запитання: «що робить цей сервер?», «як працює пошта?», «що перестане працювати, якщо я вимкну цю залізяку?». Зрозуміла структура документа значно спрощує пошук потрібної інформації. Ми, наприклад, дотримуємося наступної структури:

1. Загальний опис мережі

2. ІТ-інфраструктура
  • Мережеве обладнання
  • Фізичні сервери
  • Системи зберігання
  • Віртуальні машини
  • Периферійні пристрої
  • Оргтехніка
  • ...
3. ІТ-сервіси
  • Доменні служби Active Directory
  • Сервер оновлень WSUS
  • Служба розгортання робочих місць користувачів WDS.
  • Пошта
  • Спільна робота з документами
  • Телефонний зв'язок
  • Доступ в Інтернет
  • ...
4. Додаток
  • Ліцензії на програмне забезпечення
  • Угода про найменування
  • ...
2) Визначте, для кого ви складаєте документ
Опис ІТ-інфраструктури — один документ, інструкція — інший. Не треба намагатися вмістити в одному документі опис сервісу друку, інструкцію з надання прав доступу до принтерів та по скануванню документів на МФУ. Краще зробити 3 документа: опис ІТ-інфраструктури, інструкцію спеціаліста техпідтримки та інструкцію користувача. У цьому випадку сисадмін, эникейщик і користувач буде отримувати рівно ту інформацію, яка їм потрібна, не перегортаючи купу сторінок «зайвої інформації».

3) Допоможіть повноти, цілісності та однаковості даних
Якщо в документації у вас вказується якийсь технічний параметр в описі пристрою або сервера, то він повинен бути вказаний для всіх елементів, до яких застосовується, та, що не менш важливо, скрізь у документації цей параметр повинен називатися однаково. Якщо надалі в мережі потрібно провести якісь зміни (наприклад, змінити адресу сервера DNS), то простим пошуком по документу можна буде скласти повний список вузлів, на яких потрібно також змінити налаштування і тим самим точно спланувати проведення змін. Начебто дрібниця, а користь від документації зростає в рази.

4) Уникайте дублювання інформації
Щоб зміни в ІТ-інфраструктурі можна було легко відображати у вашому документі надалі (і тим самим підтримувати його в актуальному стані) необхідно, щоб інформацію в ньому доводилося міняти тільки в одному місці. Тобто значення параметрів того чи іншого сервера, пристрою або програми мають бути зазначені на весь документ один раз. Якщо ви в трьох місцях в документі вказали, що у такого-то сервер налаштований IP-адресу, то цілком ймовірно, що через кілька років у цьому документі сервер буде 3 різних IP-адреси і ваш документ втратить свою первинну цінність. Тільки не питайте мене, чому в таких випадках рідко хто використовує пошук по документу.

5) Не описуйте і не рекламуйте технології, не використовуйте порівняльні звороти
Іноді мені здається, що документацію за проектом в деяких компаніях ліплять на основі комерційної пропозиції. Фахівцям, які будуть читати документацію згодом, зовсім неважливо, наскільки крутий була та чи інша технологія на момент її впровадження, або чому вибір припав на неї — проект вже зроблений, і тепер залишається тільки отримати інформацію, як все було налагоджено. Фрази «високої доступності», «більш гнучко», «підвищеної надійності» і зовсім є лише особистими оціночними судженнями упорядника документації.

6) Збільшити концентрацію сенсу на одиницю тексту: використовуйте таблиці і списки
Найгірша проектна документація, яку мені довелося зустрічати, нагадувала вступне твір. Десь на третій сторінці у мене зливалися воєдино IP-адреси, маски, масиви, додаткові сервіси і логіни-паролі доступу. Щоб знайти потрібний мені параметр подібної документації доводилося читати декілька абзаців тексту, сподіваючись, що в наступному реченні мова дійде до потрібного мені значення.
Намагайтеся в документації використовувати менше не відносяться до теми слів. Корисно виносити всі значимі величини в таблиці, а замість перерахування робити списки — це дозволяє, часто просто окинувши поглядом розділ, відразу знайти потрібний параметр.

7) Одна мова викладу і менше булшита
Не «бекап», а «резервне копіювання». Не «Security», а «антивірусне ПЗ». Не «Hot Fixes» (початкова стилістика збережена), а «пакети виправлення». Ось начебто прості речі, а документація перестає ламати мозок при прочитанні.

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

9) Скріншоти доповнюють, але не замінюють текстову інформацію
В інструкції користувача, де читає, найчастіше, вперше бачить цей додаток, скріншоти просто зобов'язані супроводжувати текст. В документації на ІТ-інфраструктуру, де читає повинен вже знати, про що йде мова, скріншоти, в більшості випадків, тільки займають простір, не несуть корисної інформації. Але в обох випадках скріншоти не можуть замінювати текстову інформацію. По-перше, на них все одно нічого не побачити, особливо після роздрукування документа. По-друге, зміна налаштувань вимагатиме повторного зняття скріншота для підтримки актуальності документа. Ну і найголовніше — значення на скріншотах неможливо знайти через пошук по документу.

10) Використовуйте візуальні схеми і фотографії обладнання
Функціональна схема мережі, розташування обладнання в стійці і як виглядає саме обладнання — це не так складно зробити і додати в документ зараз, зате значно спрощує пошук потрібної залізяки через 5-6 років, коли не кожен адмін зможе сказати, як виглядає сервер HP Proliant G8 2014 року випуску.

11) Читайте написану документацію уважно. Перевіряйте текст на помилки!
Обороти виду «Централізована друк користувачів в Московському офісі Замовника здійснюється з використанням сервісу Network Printer» у виконанні лідерів ринку змушує інший раз серйозно замислитися, чи багато я знаю про можливості ІТ-технологій. Ну а про орфографічних і пунктуаційних помилки я взагалі мовчу, хоча у мене у самого була трійка з російської. Перш ніж відправити документ клієнту, внесіть в нього в різні місця пару-трійку слів-закладок і дайте віднімати його людині, яка більш-менш розуміє в граматиці. Якщо він знайде всі ваші закладки — робота зроблена добре, але головне не перегинати з використанням нецензурних слів в закладках — іноді документація разом з ними їде до клієнтів.

Успіхів!

Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.