Документация как руководство по сравнению с документацией как контрольный список

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

Я не согласен. Я думаю, что это предполагает, что все проблемы в ИТ могут быть легко сведены к простым контрольным спискам процедур восстановления. Я думаю, что это полностью игнорирует сложность ситуации, и, поскольку другие люди в отделе не всегда имеют глубокое понимание проблемы (именно поэтому я пишу документ - поэтому им есть на что сослаться ) что документация должна включать некоторые базовые справочные материалы, такие как:

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

Тем не менее, я довольно отстал в этом вопросе, поэтому моя документация должна быть переписана в форму, которая гласит: «Шаги ABC применены для решения проблемы X». Я часто слышу плач о том, что оно должно уместиться на одной странице бумаги. Попробуйте объяснить кому-то таким образом настройку ACL-списков Squid, включая устранение неполадок, в одностраничном документе. Это только один из полдюжины документов, которые «ждут записи» в качестве контрольных списков восстановления.

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

РЕДАКТИРОВАТЬ:

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

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

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

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

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

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

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

• Сотрудники, которые просто хотят знать, как сделать что-то, и не имеют времени пролистать пятнадцатистраничное руководство и выяснить, как это сделать.
• Процедуры, которые довольно сложны в действиях, но должны выполняться только время от времени.

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

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

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

Документ как руководство

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

Это документация, в которую мы включаем такие жевательные кусочки, как:

• Объясняя, почему он настроен таким образом.
  • Этот раздел может включать такие нетехнические вопросы, как политика, связанная с тем, как все это было приобретено и установлено.
• Объяснение распространенных режимов отказов и их ответов.
• Объяснение любых соглашений об уровне обслуживания, как в письменном виде, так и де-факто.
  • Де-факто: «если это не удастся в течение финальной недели, то это проблема« все по капле ». Если во время летнего перерыва вернитесь спать и займитесь этим утром».
• Установка целей обновления и рефакторинга.
  • Позже политика может измениться, почему бы нам не исправить некоторые плохие идеи, которые появились в начале?

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

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

Я понимаю, у вас есть мои симпатии.

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

Если ваш контрольный список DR выглядит так:

1. Позвони Дастину или Карен.
2. Объясните проблему.
3. Отойди.

У тебя проблема. Это не контрольный список, это признание того, что восстановление этой системы является настолько сложным, что архитектор должен это выяснить. Иногда это все, что вы можете сделать, но старайтесь избегать этого, если это вообще возможно.

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

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

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

В некоторых случаях отказа есть прямые процедуры восстановления. Документируйте их. При их документировании вы можете встретить случаи, когда списки команд вводятся в определенном порядке, что является отличным вариантом для сценариев; это может превратить процедуру восстановления на 96 пунктов в процедуру на 20 пунктов. Вы никогда не узнаете, сможете ли вы что-то написать, пока не сопоставите действие процедуры восстановления с действием.

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

На самом деле ни один, мы используем документацию как тест-кейс

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

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

Если вы не контролируете это, вы не управляете этим

Это так совершенно верно, но другой должен быть:

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

Всякий раз, когда нам нужно перенести сервисы, мы просто оставляем «Service Group», «Host Group», что бы ни применимо (мы используем Nagios, как вы можете догадаться из словаря) открытым, и оно не переносится, пока есть одна красная точка на любой из услуг.

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

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

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

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

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

Это зависит от целевой аудитории для вашей документации.

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

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

Лично я стараюсь сделать документацию максимально простой. Это имеет тенденцию включать:

• Что [X] должен делать (требования).
• Как [X] был структурирован на высоком уровне (дизайн).
• Почему я реализовал [X] так, как сделал (соображения по реализации).
• Как реализация [X] нестандартна (обходные пути).
• Общие проблемы с [X] и способы их решения (проблемы).

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

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

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

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

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

Итак, теперь, когда я написал это, я полностью согласен: пошаговые контрольные списки просто не урежут это для многих процессов.

Я полностью согласен с вами в этом (в пользу исчерпывающей документации) отчасти потому, что я привык иметь предшественников, которые вообще НЕ интересовались документами. Как было сказано в связанных постах, написание этого не только полезно для других, но и помогает вам более полно понять вашу среду и закрепить ее в своем собственном уме. Это самоцель.

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

Престижность для вас, чтобы расколоть статус-кво.

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

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

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

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

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

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

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

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