В прошлом я обсуждал с другими людьми в моем отделе документацию, в частности, уровень детализации и требования. По их мнению, документация - это простой контрольный список из Y действий, которые нужно сделать, когда X что-то пойдет не так.
Я не согласен. Я думаю, это предполагает, что все проблемы в ИТ можно легко свести к простым контрольным спискам процедур восстановления. Я думаю, что он полностью игнорирует сложность ситуации, и, поскольку другие люди в отделе не всегда имеют глубокое понимание проблемы (именно поэтому я пишу документ - так что им есть на что сослаться) ) что документация должна включать некоторые основные справочные материалы, такие как:
Тем не менее, я скорее проиграл по этому поводу, поэтому моя документация обязательный необходимо переписать в форму, которая гласит: «Выполненные шаги A-B-C решат проблему X». Я часто слышу жалобы, что это нужно уместить на одной странице бумаги. Попробуйте объяснить кому-нибудь конфигурацию ACL Squid таким образом, включая устранение неполадок, в одностраничном документе. Это лишь один из полдюжины документов, которые «ждут написания» в качестве контрольных списков восстановления.
Действительно ли метод, который я защищаю, выходит за рамки? Или они правы, и я должен просто заняться своими делами здесь и просто написать им простой контрольный список? Меня беспокоит то, что, как бы хорошо вы ни писали контрольный список процедур, он на самом деле не решает проблему, требующую, чтобы системный администратор все продумал. Если вы тратите время на составление контрольного списка процедур восстановления, которое в конечном итоге не решает проблему (поскольку есть дополнительные факторы, которые не являются частью документа, из-за узкой направленности документа), и цель документа заключалась в том, чтобы избежать повторного чтения страниц руководства, вики и веб-сайтов снова и снова, тогда почему я продвигаюсь? Я просто слишком сильно переживаю или это реальная проблема?
РЕДАКТИРОВАТЬ:
В настоящее время в отделе нет должности службы поддержки. Аудитория документации будет для других администраторов или для главы отдела.
На самом деле ни то, ни другое мы не используем Документация как тестовый
При этом мы написали документацию, которая идет с Документация как руководство. У нас были контрольные списки, но при расширении мы обнаружили, что они подвержены ошибкам и действительно дают сбой в системе в целом.
Однако у нас есть вид Установлен «Контрольный список документации», то есть, как уже упоминалось выше, мы тщательно контролируем наши услуги. Есть такая поговорка:
Если вы не контролируете это, вы не управляете им
Это совершенно верно, но должно быть другое:
Если вы не отслеживаете это, вы не документируете это
Всякий раз, когда нам нужно перенести сервисы, мы просто оставляем «Service Group», «Host Group», все, что применимо (мы используем Nagios, как вы можете догадаться из словаря), открытыми, и они не переносятся, пока есть одна красная точка. на любой из услуг.
Тесты предоставляют намного лучший контрольный список, чем любой другой письменный контрольный список. На самом деле это самодокументируется, как только у нас будет какой-то сбой, который не отслеживался, но тест, по крайней мере, будет добавлен в Nagios, при этом мы получим 2 вещи бесплатно:
«Настоящая» документация хранится в Wiki, в которой упоминаются разногласия по конкретной услуге или тесту. Если его не хватает, люди добавят его, как только нам понадобится выполнить некоторую миграцию или поработать с ним, до сих пор этот подход работал очень хорошо.
Кроме того, ошибочная документация устраняется очень быстро, каждый раз, когда что-то выходит из строя, люди начинают искать документацию и пытаются решить проблему с помощью HowTos, если что-то не так, просто обновите ее своими выводами.
Просто подумайте об ошибках, которые можно было бы создать, следуя контрольному списку и не устанавливая никаких тестов, которые после их применения покажут вам зеленый флажок. Я не думаю, что можно отделить документацию от мониторинга.
Когда я писал свой, я всегда переходил к письму два три комплекта. Контрольный список для проделанной работы, с НАМНОГО БОЛЬШЕ приложения об архитектуре системы, в том числе о том, почему все делается так, как есть, о вероятных проблемах при подключении к сети и абстрактных предположениях дизайна. за которым следует список возможных проблем и способов их решения, за которым следует более длинный раздел с информацией о том, как работает система, почему она работает таким образом, и другой информацией, полезной для указания людям в правильном направлении, если произойдет что-то уникальное.
На моей последней работе от нас требовалось написать документацию, чтобы даже люди из службы поддержки первого уровня могли восстановить работу. Для этого потребовались контрольные списки, которые обычно устаревали в течение 3 месяцев после написания. Нас настоятельно просили писать руководства по устранению неполадок, когда это возможно, но когда дерево непредвиденных обстоятельств включает в себя более трех ветвей, вы просто не можете написать этот документ, не переходя абстрактно.
когда уходящий На моей последней работе я перед отъездом сдал 100-страничное руководство «Как выполнять свою работу». В нем были абстрактные вещи, философия дизайна, а также точки интеграции. Поскольку я предположительно писал для другого системного администратора, который собирался заменить меня, я нацелил его на того, кто мог брать абстрактные идеи и превращать их в конкретные действия.
Прошло пять лет, и я считаю, что мое мнение по этому поводу несколько изменилось. Обе Документ как руководство и Документ как контрольный список занимают очень ценные места в иерархии документации, и обе должны быть созданы. Однако они нацелены на очень разные аудитории.
Документ как контрольный список
Целевым рынком для такого рода документации являются сотрудники, которые хотят знать, как что-то делать. Они бывают двух типов:
Нетерпение - движущая сила первого рода. Может быть, ваш коллега на самом деле не хочет знать Зачем вывод должен быть передан через регулярное выражение Perl из 90 символов, просто чтобы закрыть заявку. Обязательно включите утверждение вроде «Чтобы получить подробное объяснение того, почему этот рабочий процесс выглядит так, перейдите по этой ссылке» в контрольный список для тех, кто действительно хочет знать, почему.
Второй момент касается процедур, которые выполняются не часто, но содержат подводные камни. Контрольный список действует как карта, чтобы избежать Несомненной Гибели, просто взорвав ее. Если контрольный список хранится в репозитории документации, это избавляет от необходимости искать электронную почту на то время, когда старый администратор разослал HOWTO.
по моему мнению хорошо Контрольный список-документация также включает разделы о возможных точках отказа и ответах на эти отказы. Это может сделать документ довольно большим и вызвать отклики TL; DR в коллегах, поэтому я считаю, что создание ссылок на режимы отказа и их ответы из контрольного списка, а не на самой странице, делает контрольный список небрежным. Примите гипертекстуальность.
Документ как руководство
Целевой рынок для такого рода документации - люди, которые хотят больше узнать о том, как работает система. Документацию в стиле практических действий можно извлечь из этой документации, но чаще я рассматриваю ее как дополнение к документации в стиле контрольного списка для поддержки решений, принятых в рабочем процессе.
Это документация, в которую мы включаем такие жевательные части, как:
Все это очень полезно для получения всестороннего понимания всей системы. Вам не нужно всестороннее понимание, чтобы выполнять простые задачи автоматизации, выполняемые человеком, вам нужно понять, почему что-то сломалось, и иметь представление, как заставить это не делать этого снова.
Вы также упомянули документацию по аварийному восстановлению, которая должна быть контрольным списком.
Я понимаю, вам мои соболезнования.
Да, документация по аварийному восстановлению должна быть как можно более похожей на контрольный список.
Да, документация по аварийному восстановлению наиболее устойчива к контрольным спискам из-за того, что все может сломаться.
Если ваш контрольный список DR выглядит так:
- Позвони Дастину или Карен.
- Объясните проблему.
- Отойди.
У тебя проблемы. Это не контрольный список, это признание того, что восстановление этой системы настолько сложно, что архитектор должен разобраться. Иногда это все, что вы можете сделать, но старайтесь избегать этого, если возможно.
В идеале документация по аварийному восстановлению содержит контрольные списки процедур для нескольких разных вещей:
Иногда процедуры сортировки - это вся документация аварийного восстановления, которую вы можете составить для некоторых систем. Но его наличие означает, что вызов в 4 часа утра будет более понятным, и старший инженер, выполняющий восстановление, сможет быстрее решить реальную проблему.
В некоторых случаях отказа предусмотрены простые процедуры восстановления. Задокументируйте их. Документируя их, вы можете обнаружить случаи, когда списки команд вводятся в определенном порядке, что является отличным вариантом использования для написания сценариев; он может превратить процедуру восстановления с 96 точками в процедуру с 20 точками. Вы никогда не поймете, можете ли вы написать что-нибудь, пока не сопоставите процедуру восстановления действие за действием.
Документация в ручном стиле для случаев сбоя - это последний упор, который следует использовать, когда нет процедур восстановления или процедуры восстановления не прошли. Он предоставляет подсказки Google, необходимые, чтобы, возможно, найти кого-то еще, у кого была эта проблема, и что они сделали, чтобы ее исправить.
Это зависит от целевой аудитории вашей документации.
Для типов службы поддержки (уровень 1) правильным решением будет контрольный список; конечно, это предполагает наличие более высоких уровней поддержки с более глубокими знаниями, которые вы описываете.
Если документация предназначена для группы систем, я всегда ошибаюсь в пользу большего количества документации. Достаточно сложно иметь адекватную документацию, чтобы просто обойтись, если кто-то (вы) хочет написать более обширные документы с необходимой справочной информацией - ни один здравомыслящий человек не должен стоять на вашем пути!
Лично я стараюсь максимально упростить документацию. Он обычно включает:
Так что, по общему признанию, мой раздел общих проблем, вероятно, будет кратким описанием того, что произошло, и пошаговыми руководствами по точкам, как это исправить.
Я обычно предполагаю, что у читателя есть некоторые знания о рассматриваемой системе (если только это не является особенно загадочным). У меня нет времени делать большую часть моей технической документации уровня 1 или руководства читаемой, но подсказка уровня 3 должна быть в порядке.
Я думаю, это явно зависит от темы. Не все можно свести к простому контрольному списку, и не все требует подробного руководства пользователя.
Это определенно звучит так, будто вы говорите о внутренней документации, и, по моему опыту, вы не можете просто дать список шагов, потому что существует слишком много вариантов. Даже создание учетной записи пользователя имеет некоторые параметры (в нашей среде), поэтому в нашем документе «Новая учетная запись» перечислены основные шаги по порядку, но для каждого шага есть описание возможных вариантов.
С другой стороны, мы так и не успели написать большую часть документа «Как установить патч в офисе», но наш очень схематичный документ также не был контрольным списком - в нем упоминалось соглашение, которое мы использовали для цветов кабелей, подчеркнуто что ты было чтобы обновить электронную таблицу, в которой перечислены соединения, и на этом все.
Итак, теперь, когда я написал это, я полностью согласен: пошаговые контрольные списки просто не годятся для многих процессов.
Я полностью согласен с вами в этом (в пользу исчерпывающей документации) отчасти потому, что я привык к своим предшественникам, которые вообще НЕ интересовались документацией. Как было сказано в связанных сообщениях, написание этого не только полезно для других, но и помогает вам более полно понять свою среду и укрепить ее в своей своя разум. Это самоцель.
Кроме того, я считаю, что большая часть возражений возникает из-за странного убеждения, что дрянная / несуществующая документация = безопасность работы. Такое мышление кажется нечестным и сомнительным.
Престижность вам за нарушение статус-кво.
Я довольно много документирую, у меня даже есть контрольный список приоритетов документов :-), однако я не буду документировать вещи, которые можно считать общими знаниями (т.е. разумное хорошее описание проблемы дает ответ на первой странице Google).
Для всех, кто интересуется, вот мой контрольный список doc prio (работает для меня, может не для вас, комментарии и предложения высоко ценятся):
Контрольный список - это хорошо, если он не притворяется полный документация. Последние несколько документов, которые я написал, состояли из двух частей: XYZ для пользователей, которые включали красивые снимки экрана о том, как его использовать; и XYZ для системных администраторов, в котором рассказывалось, как он был настроен и почему (возможно, даже включая бизнес-требования для его существования), ловушки, которых следует избегать, и раздел по устранению неполадок. Устранение неполадок - вот где я ожидал бы найти контрольные списки. Возможно, написание контрольных списков как XYZ для службы технической поддержки может помочь в этом.
Теперь, если читать между строк и сосредоточиваться только на контрольных списках, это указывает на отсутствие мышления «общей картины» и долгосрочного планирования, которых я ожидал бы от человека, который: когда-либо оказывал техническую поддержку; или младший админ только начинающий; или он так завален работой, что у них нет времени думать об этом; или его никогда не заставляли думать об этом; или просто наплевать. Я не знаю, какие из них применимы в вашем случае.
Я очень разбираюсь в документации. Компания, в которой я сейчас работаю, считает, что документация важна, но некоторые люди в компании считают, что у них нет времени писать документацию. Это может усложнить жизнь любому, кроме человека, который это сделал изначально.
По некоторым вещам я написал пошаговые инструкции. Вы можете назвать это контрольным списком, если хотите, но на самом деле он не предназначен для физической проверки. Я называю свой стиль документации «ступеньками детского сада». Он создан по образцу тетради MCSE, который я взял на один из экзаменов по Windows 2000. Шаги очень подробны, но использование жирного шрифта / курсива / шрифта позволяет легко замалчивать и просто выделять важные части, поэтому вам не нужно читать все после того, как вы изучите шаги.
Некоторые вещи не подходят для пошаговых инструкций, поэтому я стараюсь предоставить как можно больше данных конфигурации. Некоторые технически подкованные люди, которые в конечном итоге продолжают поддерживать их, будут лучше понимать, с чем они сталкиваются, и, надеюсь, это облегчит их жизнь, когда что-то пойдет не так.