Документация As-A-Manual и Документация As-A-Checklist

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

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

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

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

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

EDIT:

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

17 голосов | спросил Avery Payne 14 J0000006Europe/Moscow 2009, 09:16:55

9 ответов


11

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

Если ваш контрольный список DR выглядит следующим образом:

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

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

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

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

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

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

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

ответил sysadmin1138 14 J0000006Europe/Moscow 2009, 09:28:28
14

На самом деле ни то, ни другое, мы используем Documentation As-a-Testcase

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

Однако у нас есть вид "Документация As-a-Checklist", то есть, как упоминалось выше, мы внимательно отслеживаем наши услуги. Есть поговорка:

  

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

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

  

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

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

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

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

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

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

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

ответил serverhorror 14 J0000006Europe/Moscow 2009, 19:59:05
5

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

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

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

ответил Joe 14 J0000006Europe/Moscow 2009, 09:20:49
5

Лично я стараюсь держать документацию как можно проще. Он включает в себя:

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

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

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

ответил Neobyte 14 J0000006Europe/Moscow 2009, 19:41:32
4

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

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

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

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

ответил Ward 14 J0000006Europe/Moscow 2009, 09:39:12
3

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

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

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

ответил Kara Marfia 14 J0000006Europe/Moscow 2009, 19:17:03
3

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

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

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

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

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

ответил pgs 15 J0000006Europe/Moscow 2009, 08:12:42
1

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

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

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

ответил Scott 14 AM00000010000002731 2009, 01:50:27

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132