Посібник з документацією та контрольним списком документації

У минулому я дискутував з іншими людьми у своєму відділі щодо документації, зокрема, рівня деталізації та вимог. На їхню думку, документація - це простий контрольний список Y-речей, які потрібно робити, коли X речі йдуть не так.

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

• Призначення відповідної (під) системи
• Чому це налаштовано таким чином
• Очікування подій, які відбудуться при виконанні налаштувань / процедур
• Потенційні проблеми, які можуть спричинити збій процедури

Однак я скоріше переживаю це, тому мою документацію потрібно переписати у форму, в якій написано "Кроки ABC, застосовані для того, щоб вирішити проблему X". Я часто чую плач, який йому потрібно вмістити на одну сторінку паперу. Спробуйте пояснити конфігурацію ACL-кодів Squid комусь таким чином, включаючи усунення несправностей, через документ на одній сторінці. Це лише один з півдесятка документів, які "чекають, щоб їх написали" як контрольні списки.

Чи дійсно метод, який я відстоюю, переборював? Або вони праві, і я повинен просто заперечити тут свою справу і просто написати їм простий контрольний список? Мене хвилює те, що, як би добре ви не писали контрольний список, це насправді не вирішує проблему, яка вимагає, щоб SysAdmin продумав все. Якщо ви витрачаєте час, роблячи контрольний список процедур відновлення, який не вирішує проблему (оскільки існують додаткові фактори, які не входять до документа, через вузьку спрямованість документа ) та цілі Документ полягав у тому, щоб уникнути повторного читання сторінок, а також вікі-сайтів та веб-сайтів знову, чому я переглядаю ці пропозиції? Я просто переживаю занадто багато, чи це справжня проблема?

Редагувати:

Наразі у відділі немає посади служби технічної допомоги. Аудиторія для документації буде для інших адміністраторів або для керівника відділу.

При написанні моєї я завжди перетворювався на написання двох трьох наборів. Контрольний список, який виконується, з додатком МНОГО ДЛЮШЕ про архітектуру системи, включаючи те, чому все робиться таким, яким вони є, ймовірними точками приходу в Інтернет та абстрактними припущеннями щодо дизайну. Далі йде список можливих проблем та їх вирішення, а потім довший розділ з інформацією про те, як працює система, чому це робиться саме так, та іншою інформацією, корисною для орієнтації людей у ​​правильному напрямку, якщо трапиться щось унікальне.

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

При виході моєї останньої роботі, я повернувся в 100 сторінки «Як зробити свою роботу» керівництво перед від'їздом. У ньому були абстрактні речі, філософія дизайну, а також точки інтеграції. Оскільки я, мабуть, писав про іншого сисадміна, який збирався замінити мене, я спрямував це на когось, хто міг би приймати абстрактні поняття і перетворювати їх на конкретні дії.

Минуло п’ять років, і я вважаю, що моя думка з цього приводу дещо змінилася. Як Документ як посібник, так і документ як контрольний список мають дуже цінні місця в ієрархії документації, і обидва потрібно створити. Хоча вони націлені на дуже різні аудиторії.

Документ як контрольний список

Цільовим ринком такого роду документації є співробітники, які хочуть, як зробити щось. Вони бувають двох видів:

• Співробітники, які просто хочуть знати, як зробити щось, і не встигають переглядати посібник із п’ятнадцяти сторінок і придумувати кроки для себе.
• Процедури, які є досить складними за кроками, але їх потрібно виконувати лише раз у раз.

Нетерпіння - це рушій першого типу. Можливо, ваш колега насправді не хоче знати, чому результат повинен бути прокладений через 90 символів пергель, просто це має бути для закриття квитка. Однозначно включіть заяву на кшталт "Для детального пояснення, чому такий робочий процес виглядає таким чином, перейдіть за цим посиланням" у контрольний список для тих, хто хоче знати, чому.

Другий момент - це процедури, які не виконуються часто, але містять підводні камені. Контрольний список виступає як карта, щоб уникнути певної долі просто крилати його. Якщо контрольний список зберігається в репортажі документації, це заощаджує необхідність пошуку електронної пошти протягом часу, коли старий адміністратор розіслав HOWTO.

На мою думку, хороша контрольна документація включає також розділи про можливі пункти відмов та відповіді на ці збої. Це може зробити документ досить великим і викликати відповіді TL; DR у колег, тому я вважаю, що перетворення режимів відмов та їх відповідей є посиланням із контрольного списку, а не на самій сторінці, створюючи несанкціонований контрольний список. Отримати гіпертекстуальність.

Документ як посібник

Цільовим ринком такого роду документації є люди, які хочуть дізнатися більше про те, як працює система. Документація стилю "робити щось" повинна бути отримана з цієї документації, але частіше я бачу це як доповнення до документації в стилі контрольного списку для резервного копіювання рішень, прийнятих у робочому процесі.

Це документація, де ми включаємо такі жувальні шматочки, як:

• Пояснення, чому це налаштовано таким чином.
  • Цей розділ може містити такі нетехнічні питання, як політика щодо того, як все було придбано та встановлено.
• Пояснення загальних режимів відмов та їх реакцій.
• Пояснення будь-яких угод про рівень обслуговування, як письмових, так і фактичних.
  • Де-факто: "Якщо цього не вдасться під час тижня фіналу, це проблема, що стосується крапель. Якщо під час літньої перерви, поверніться спати і займайтеся цим вранці".
• Постановка цілей оновлення та рефакторингу.
  • Пізніше політика може бути іншою, чому б ми не виправити деякі погані ідеї, запроваджені на початку?

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

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

Я розумію, у вас є мої симпатії.

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

Якщо ваш контрольний список щодо DR виглядає так:

1. Телефонуй Дастін або Карен.
2. Поясніть проблему.
3. Відійди.

У вас проблема. Це не контрольний список, це визнання, що відновлення цієї системи є настільки складним, що архітектор потребує з'ясування. Іноді це все, що ти можеш зробити, але намагайся уникати цього, якщо це можливо.

В ідеалі документація щодо DR містить контрольні списки процедур для кількох різних речей:

• Процедури трелінгу, щоб з’ясувати, що пішло не так, що допоможе виявити ...
• Процедури відновлення певних випадків відмов. Що підтримується ...
• Сценарії відновлення, написані заздалегідь, допоможуть мінімізувати помилки людини під час відновлення.
• Документація в ручному стилі про випадки відмов, чому вони виникають і що вони означають.

Процедури обрізання - це іноді вся документація на DR, яку ви можете виготовити для деяких систем. Але якщо це означає, що виклик 4 ранку буде більш зрозумілим, і старший інженер, що здійснює відновлення, зможе швидше дістатись до реальної проблеми.

Деякі випадки відмов мають прямі процедури відновлення. Задокументуйте їх. Під час документування їх можна виявити випадки, коли списки команд вводяться в певному порядку, що є чудовим випадком використання сценаріїв; це може перетворити 96-бальну процедуру відновлення в 20-бальну. Ви ніколи не зрозумієте, чи зможете ви щось скриптувати, поки не зіставите дію процедури відновлення за дією.

Документація в ручному стилі для випадків несправностей - це останній задній стоп канави, який слід використовувати, коли немає процедур відновлення або не вдалося відновити процедури відновлення. Він пропонує підказки google, необхідні, щоб знайти когось іншого, у кого була ця проблема, і що вони зробили для її усунення.

Насправді ні те, ми не використовуємо документацію As-a-Testcase

Це було сказано, що у нас є письмова документація, яка йде разом із посібником з документації . Ми мали контрольні списки, але під час вирощування ми виявили, що вони схильні до помилок і справді не спрацьовують у системі в цілому.

Однак у нас встановлено певний "Документальний контрольний список", тобто - як було сказано вище - ми ретельно контролюємо наші послуги. Є приказка:

Якщо ви не стежите за цим, ви не керуєте цим

Це так повністю, але іншим має бути:

Якщо ви не стежите за цим, ви не документуєте це

Щоразу, коли нам потрібно мігрувати сервіси, ми просто тримаємо "Сервісну групу", "Хост-групу", що б там не було (ми використовуємо Nagios, як ви здогадаєтесь із словника) відкритими, і вони не мігруються до тих пір, поки є одна червона точка на будь-якій з послуг.

Тести забезпечують набагато кращий контрольний список, ніж будь-який рукописний контрольний список. Це фактично самодокументування, як тільки у нас є якісь збої, за якими ще не відстежувались, тест буде принаймні доданий до Nagios, завдяки чому ми отримуємо 2 речі безкоштовно:

• ми знаємо, коли це не вдається
• ще один пункт у контрольному списку

"Справжня" документація зберігається у Вікі, де згадуються шанси та кінці конкретної послуги або тесту. Якщо він відсутній, люди додадуть його, як тільки нам потрібно зробити деяку міграцію або потрібно виконати якусь роботу, поки що цей підхід спрацював дуже добре.

Крім того, помилкова документація випрасовується дуже швидко, кожен раз, коли щось не вдається, люди починають шукати документацію і намагаються вирішити проблему з HowTos там, якщо це неправильно, просто оновіть її зі своїми висновками.

Подумайте лише про помилки, які, можливо, можна створити, дотримуючись контрольного списку та не встановивши жодних тестів, які дадуть вам зелений прапорець після їх застосування. Я не думаю, що неможливо відокремити Документацію від Моніторингу.

Це залежить від цільової аудиторії вашої документації.

Для типів довідкової служби (рівень 1) контрольний список - це правильний шлях; Звичайно, це передбачає, що існують більш високі рівні підтримки з глибшими знаннями, які ви описуєте.

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

Особисто я намагаюся зберігати документацію максимально просто. Вона включає:

• Що [X] повинен робити (вимоги).
• Як [X] було структуровано на високому рівні (дизайн).
• Чому я реалізував [X] так, як я це зробив (міркування щодо впровадження).
• Наскільки реалізація [X] нестандартна (обхідні шляхи).
• Поширені проблеми з [X] та способи їх вирішення (проблеми).

Тож, мабуть, мій розділ із поширеними проблемами, ймовірно, буде коротким описом того, що трапилося, і крапки з точки зору, як це виправити.

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

Я думаю, це очевидно залежить від теми. Не все можна звести до простого контрольного списку, і не все потребує докладного посібника користувача.

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

З іншого боку, нам ніколи не доводилося писати багато документів на тему "Як виправити патч в офісі", але наш дуже схематичний документ також не був контрольним списком - він зазначав конвенцію, яку ми використовували для кольорів кабелів, підкреслював що вам довелося оновити електронну таблицю, яка перераховувала з'єднання, і це стосувалося цього.

Отже, тепер, коли я це писав, я повністю згоден: покрокові контрольні списки просто не вирізатимуть це для багатьох процесів.

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

Як осторонь, я вважаю, що велика кількість відштовхувань походить від дивної віри в те, що шалена / неіснуюча документація = безпека роботи. Таке мислення просто здається нечесним і тінистим.

Кудо вам для того, щоб підкріпити статус-кво.

Я документую досить багато, навіть у мене є контрольний список пріоритетів документа :-), проте я не буду документувати речі, які можна вважати загальними знаннями (тобто розумний хороший опис проблеми дає відповідь на першій сторінці google).

Для всіх, хто тут зацікавлений, це мій контрольний список документів (працює для мене, можливо, для вас, коментарі та пропозиції високо оцінюються):

1. Створіть особистий журнал / щоденник, в який ви записуєте все, що ви робили / знали розумно
2. Послуги, яка служба - де, для чого це робиться і для кого це робиться (будь-які угоди про угода про угоду? Чи варто їх створювати?)
3. Сервери, який сервер - де, скільки років і коли на ньому написано
4. Як зазначено вище, але для мережевого обладнання, ДБЖ тощо
5. Як зазначено вище, але для всіх машин користувача
6. Макет фізичної мережі (який кабель йде, куди триває і яка вимірюється якість)
7. Огляд конфігурації програмного забезпечення та ліцензій для серверів
8. Огляд конфігурації програмного забезпечення та ліцензій для користувачів користувачів
9. Огляд конфігурації комутаторів, маршрутизаторів та іншого спеціального обладнання
10. Контракти та угода про домовленість за всіма сторонніми сторонами, від яких моя послуга безпосередньо залежить (ISP, домен тощо)
11. Налаштуйте систему квитків з інтегрованою вікі, щоб помістити в неї всі вищевказані речі.
12. На кожен інцидент створюйте квиток (навіть якщо ви використовуєте його лише для себе).
13. Створіть сценарій, який у неділю збирає квитки та групує їх за проблемним типом.
14. У понеділок створіть автоматичне рішення або документ, що містить кінцевий користувач, для найпоширенішої проблеми
15. Якщо дозволяє час, зробіть наступний.
16. Якщо більше нічого не робити, шукайте нову роботу і дайте людині, яка замінює вам журнал ;-)

Контрольний список є прекрасним, якщо він не претендує на повний документацію. Останні декілька написаних нами документів виходили з двох частин: XYZ для користувачів, які містили досить скріншоти щодо того, як ним користуватися; та XYZ для системних адміністраторів, де було вказано, як було налаштовано, і чому (можливо, навіть включаючи вимоги бізнесу для його існування), пастки, яких слід уникати, та розділ про усунення несправностей. Виправлення неполадок - це те, де я сподіваюся знайти контрольні списки. Можливо, написання контрольних списків як XYZ для технічної підтримки може допомогти задуматися.

Тепер, читаючи між рядками, зосереджуючись лише на контрольних списках, вказує мені на відсутність «великої картини» мислення та довгострокового планування, чого я б очікував від того, хто: тільки коли-небудь робив технічну підтримку; або молодшого адміністратора, який тільки починається; або так завалений роботою, що в них немає часу думати про це; або ніколи не підштовхували його думати; або просто просто не байдуже. Я не знаю, які з них, якщо такі є, застосовуються у вашому випадку.

Я досить великий в документації. Компанія, в якій я зараз працюю, вважає, що документація важлива, але деякі люди в компанії вважають, що не мають часу написати документацію. Це може ускладнити життя нікому, крім людини, яка спочатку це зробила.

Для певних речей я написав покрокові інструкції. Ви можете назвати це контрольним списком, якщо хочете, але це не дійсно призначене для фізичної перевірки. Я називаю свій стиль документації «кроками дитячого садка». Він з малюнком після навчальної книги MCSE, яку я склав для одного з іспитів на Windows 2000. Етапи дуже детальні, але використання жирного шрифту / курсиву / шрифту дозволяє легко промальовувати та просто вибирати важливі частини, тому вам не потрібно буде читати все після того, як ви дізналися ці кроки.

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