Документация As-Manual по сравнению с поскольку-контрольным-списком документации
Существует функция Intel под названием PAE, который в действительности позволяет ОС использовать больше чем 4 ГБ памяти. Каждое приложение может только использовать 2 (или 3) ГБ пространства памяти, но поскольку ОС теперь имеет больше памяти для распространения, материал по - там будет менее совместно использовать между процессами и следовательно некоторыми возможными выигрышами в производительности.
Реальное волшебство однако начинается при использовании API AWE, с которым можно на самом деле использовать больше памяти с единственным приложением на 32 бита, которое особенно записано для этого. Это - то, что делает SQL Server.
При записи моего я всегда опускался до записи два три набора. get-er-done контрольный список, с НАМНОГО БОЛЕЕ ДЛИННЫМ приложением об архитектуре системы включая то, почему вещи сделаны путем, они, вероятные камни преткновения при прибытии онлайн и абстрактные предположения дизайна. сопровождаемый списком вероятных проблем и их разрешений, сопровождаемых более длинным разделом с информацией о том, как система работает, почему это делает это, тот путь и другая информация, полезная для указания на людей в правильном направлении, должны что-то уникальное происходить.
В моем последнем задании мы были обязаны писать документ так, чтобы даже люди справочной службы уровня 1 могли возвратить вещи. Это потребовало контрольных списков, которые обычно становились устаревшими в течение 3 месяцев после записи. Нас сильно убедили записать руководства по поиску и устранению неисправностей, когда это возможно, но когда дерево непредвиденного обстоятельства получает больше чем три ответвления в нем, Вы просто не можете записать что документ без идущего краткого обзора.
При отъезде моего последнего задания я повернулся на 100 страницах, 'как сделать мое задание' руководство, прежде чем я уехал. Это имело абстрактный материал в нем, принципы проектирования, а также точки интеграции. Так как я, по-видимому, писал для другого системного администратора, который собирался заменить меня, я нацелил его на кого-то, кто мог взять абстрактные понятия и превратить их в конкретные действия.
Пять лет передали, и я нахожу, что мое мнение об этом сместилось несколько. И Документ, столь же Ручной и Документ как Контрольный список, имеют очень ценные места в иерархии документации и обеих потребностей, которые будут произведены. Они предназначаются для совсем других зрителей, все же.
Документ как контрольный список
Целевой рынок для этого вида документации является коллегами, которые хотят к как, как сделать вещь. Они прибывают в два типа:
- Коллеги, которые просто хотят знать, как сделать вещь и не имеют времени, чтобы просмотреть руководство на пятнадцать страниц и выяснить шаги для себя.
- Процедуры, которые довольно сложны на шагах, но только должны быть выполнены время от времени.
Нетерпение является драйвером для первого вида. Возможно, Ваш коллега на самом деле не хочет знать, почему вывод должен быть передан по каналу через 90 символьного жемчуга regex, просто что он должен быть в порядке для закрытия билета. Определенно включайте оператор как, "Для подробного объяснения того, почему этот рабочий процесс похож на это, перейдите по этой ссылке", в контрольном списке для тех, которые действительно хотят знать почему.
Вторая точка для процедур, которые часто не выполняются, но содержат ловушки. Контрольный список действует как карта для предотвращения Определенной Гибели просто winging это. Если контрольный список сохранен в документации repo, он сохраняет необходимость искать электронную почту в течение времени, старый администратор отослал ПРАКТИЧЕСКОЕ РУКОВОДСТВО.
По-моему, хорошая документация контрольного списка также включает разделы по возможным местам ошибки и ответы на те отказы. Это может сделать документ довольно большим и инициировать TL; ответы DR в коллегах, таким образом, я нахожу, что, делая виды отказа и их ответы ссылка из контрольного списка, а не на самой странице делает для нестрашного контрольного списка. Гиперсмысловая структура объятия.
Документ как руководство
Целевой рынок для этого вида документации является людьми, которые хотят узнать больше, как работает система. Документация стиля how-to-do-a-thing должна смочь быть полученной на основании этой документации, но чаще всего я вижу, что она как дополнение к документации стиля контрольного списка для резервного копирования решений сделала в рабочем процессе.
Это - документация, где мы включаем такие требующие продолжительного жевания части как:
- Объяснение, почему это настроило этот путь.
- Этот раздел может включать такие нетехнические вопросы как окружение политики, как все это было куплено и установлено.
- Объяснение режимов общего отказа и их ответов.
- Объяснение любых соглашений об уровне обслуживания, и записанных и фактических.
- Де-факто: "если это перестало работать в течение недели финала, это - отбрасывание - все проблема. Если во время летних каникул, вернитесь ко сну и соглашению с ним утром".
- Изложение обновления и рефакторинг целей.
- Политика может отличаться позже, почему мы не фиксируем некоторые плохие идеи, которые представили в начале?
Которые все очень полезны для получения всестороннего понимания целой системы. Вам не нужно всестороннее понимание для выполнения простых задач человеческой автоматизации, Вам нужно оно для выяснения, почему что-то повредило способ, которым оно сделало и имеет идею, где заставить его не сделать этого снова.
Вы также упомянули документацию Аварийного восстановления, которая должна быть контрольным списком.
Я понимаю, у Вас есть мое сочувствие.
Да, документация DR действительно должна быть максимально подобной контрольному списку.
Да, документация DR является самой стойкой к checklisting из-за того, сколько путей вещи могут повредиться.
Если Ваш контрольный список DR похож:
- Позвоните Dustin или Karen.
- Объясните проблему.
- Отступить.
У Вас есть проблема. Это не контрольный список, который является подтверждением, что восстановление этой системы так сложно, это берет архитектора для выяснения. Иногда это - все, что можно сделать, но стараться избегать его если вообще возможный.
Идеально документация DR содержит контрольные списки процедуры для нескольких разных вещей:
- Процедуры медицинской сортировки для выяснения, что пошло не так, как надо, который поможет определить...
- Процедуры восстановления определенных случаев возникновения отказов. Который поддерживается...
- Сценарии восстановления, записанные хорошо заранее, чтобы помочь минимизировать человеческую ошибку во время восстановления.
- Документация ручного стиля о случаях возникновения отказов, почему они происходят и что они имеют в виду.
Процедуры медицинской сортировки иногда являются всей документацией DR, которую можно сделать для некоторых систем. Но наличие его означает, что выноска 4:00 будет более понятной, и старший инженер, делающий восстановление, сможет достигнуть фактическую проблему быстрее.
Некоторые случаи возникновения отказов имеют простые процедуры восстановления. Зарегистрируйте их. При документировании их можно найти случаи, где списки команд вводятся в определенный порядок, который является большим примером использования для сценариев; это может превратить, 96 процедур восстановления точки в 20 указывают на тот. Вы никогда не будете выяснять, можно ли написать сценарий чего-то, пока Вы не отображаете действие процедуры восстановления действием.
Документация ручного стиля для случаев возникновения отказов является последней поддержкой, которая будет использоваться, когда НЕТ никаких процедур восстановления или отказавших процедур восстановления. Это обеспечивает, подсказки Google должны были, возможно, найти кого-то еще, у кого была та проблема и что они сделали для фиксации его.
-
1Это звучит очень похожим на среду I' m в (минус справочная служба). +1 для " почему я сделал это это way" – Avery Payne 14 June 2009 в 08:33
На самом деле ни один, мы используем Поскольку-тестовый-сценарий Документации
Это сказанное мы записали документацию, которая идет с Документацией As-Manual. Мы имели в распоряжении контрольные списки, но при росте мы нашли, что они были подвержены ошибкам и действительно провальны в системе в целом.
У нас действительно однако есть вид "Поскольку-контрольного-списка Документации" установленным, который является - как упомянуто выше - мы экстенсивно контролируем наши сервисы. Существует высказывание:
Если Вы не контролируете его, Вы не управляете им
Это таким образом полностью верно, но другой должен быть:
Если Вы не контролируете его, Вы не документируете его
Каждый раз, когда мы должны переместить сервисы, мы просто сохраняем "Service Group", "Группа узлов", независимо от того, что применяется (мы используем Nagios, как можно предположить из словаря) открытый и он не перемещен, пока существует единственная красная точка на любом из сервисов.
Тесты предоставляют намного лучший контрольный список, чем какой-либо рукописный контрольный список мог обеспечить. Это на самом деле сам документирование, как только у нас есть некоторый отказ, который еще не контролировался, тест будет, по крайней мере, добавлен к Nagios, с этим мы получаем 2 Вещи бесплатно:
- мы знаем, когда это перестало работать
- другая точка в контрольном списке
"Реальная" документация сохранена в Wiki, упомянув ненужные детали определенного сервиса или теста. Если это будет отсутствовать, то люди добавят его, как только мы должны сделать некоторую миграцию или должны сделать некоторую работу с нею, до сих пор тот подход работал очень хороший.
Также ошибочная документация сглажена действительно быстро, каждый раз что-то перестало работать, люди начинают искать документацию и пытаются решить вопрос с HowTos там, если это неправильно, просто обновляют его с Вашими результатами.
Просто думайте об ошибках, можно было возможно создать следующим контрольный список и не устанавливавший любые тесты, которые дадут Вам зеленый флажок после применения их. Я не думаю, что возможно разделить Документацию от Контроля.
-
1
-
2Я посмотрел, что аккуратное видео YouTube демонстрировало систему, которая делает интеграцию / приемочные испытания и записывает скринкасты. youtube.com/watch?v=78mts_sKNGs – jldugger 15 June 2009 в 07:59
Это зависит от целевой аудитории для Вашей документации.
Для справочной службы (уровень 1) вводят, контрольный список является корректным способом пойти; конечно, это предполагает, что существуют более высокие уровни поддержки с более глубоким знанием, которое Вы описываете.
Если документация для системной группы, я всегда допускаю ошибку на стороне большего количества документации. Достаточно трудно иметь соответствующую документацию только для продвижений, если кто-то (самостоятельно) хочет записать более обширные документы с необходимой справочной информацией - никакой нормальный человек не должен стоять на пути!
-
1+1 Документация должна всегда писаться с целевой аудиторией в памяти. Они читают, документ для вытаскивания чего-то из него... - то, что знание или является этим, как сделать что-то. Если, как сделать что-то, что может потребовать небольшого количества дополнительного знания I' ve нашел, что помещение дополнительного знания в Приложении является хорошим способом пойти. – Paul Rowland 14 August 2009 в 04:39
Лично я пытаюсь сохранить документацию максимально простой. Это имеет тенденцию включать:
- Что [X], как предполагается, делает (требования).
- Как [X] был структурирован на высоком уровне (дизайн).
- Почему я реализовал [X] в пути, я сделал (рекомендации по внедрению).
- Как реализация [X] нестандартна (обходные решения).
- Распространенные проблемы с [X] и как разрешить их (проблемы).
Таким образом, по общему признанию мой раздел распространенных проблем, вероятно, будет кратким описанием того, что произошло и точечные пошаговые демонстрации точки о том, как зафиксировать его.
Я обычно принимаю некоторое знание от читателя рассматриваемой системы (если это не особенно тайно). У меня нет времени для создания большей части моего уровня 1 технической документации или управления читаемыми - но cluey уровень 3 должен быть прекрасным.
Я думаю, что это, очевидно, зависит от темы. Не все может быть уменьшено до простого контрольного списка, и не все нуждается в подробном руководстве пользователя.
Это, конечно, кажется, что Вы говорите о внутренней документации, и по моему опыту Вы не можете только дать список шагов, потому что существует слишком много вариантов. Даже создание учетной записи пользователя имеет некоторые опции (в нашей среде) так наша "Новая Учетная запись" списки документов, основные шаги в порядке, но для каждого шага имеет описание того, каковы изменения.
С другой стороны, мы никогда не находили время для записи большой части документа для, "Как исправить в офисе", но наш очень поверхностный документ также не был контрольным списком - это упомянуло конвенцию, которую мы использовали для цветов кабелей, подчеркнул, что необходимо было обновить электронную таблицу, которая перечислила соединения, и это было об этом.
Так, теперь, когда я записал это, я полностью соглашаюсь: пошаговые контрольные списки просто не сократят его для большого количества процессов.
Я сильно соглашаюсь с Вами на этом (в пользу исчерпывающей документации) частично, потому что я привык иметь предшественников, у которых НЕ было большого интереса к документам вообще. Как был сказан в связанных сообщениях, выписывание его не только хорошо для других, но и помогает Вам более полно понять свою среду и укрепить его в Вашем собственном уме. Это - конец к себе.
Как в стороне, я нахожу, что много pushback прибывает из нечетной веры что дрянная/несуществующая документация = обеспеченность работой. Такие взгляды просто кажутся нечестными и теневыми.
Благодарность Вам для маркировки статус-кво.
Контрольный список прекрасен, пока он не симулирует быть подробной документацией. Последние несколько документов, которые я записал, появились в две части: XYZ для Пользователей, которые включали довольно снимки экрана в то, как использовать его; и XYZ для Системных администраторов, которые включали, как это была установка, и почему (возможно даже включая бизнес-требование для него для существования), прерывания для предотвращения, и раздел по поиску и устранению неисправностей. Поиск и устранение неисправностей состоит в том, где я ожидал бы находить контрольные списки. Возможно, при записи контрольных списков, поскольку XYZ для Технической поддержки мог бы помочь высказать мнение.
Теперь, читать между строк, фокусировка только на контрольных списках указывают мне на отсутствие "Большого Изображения" взгляды и длительный срок, планируя это, я ожидал бы от кого-то кто: только когда-либо делал техническую поддержку; или младший администратор, только начинающий; или так затопляется работой, у них нет времени думать об этом; или никогда не продвигался думать об этом; или просто не заботится. Я не знаю, какой из них, если таковые имеются, применяют в Вашем случае.
Я документирую довольно много, у меня даже есть приоритетный контрольный список документа :-), однако я не зарегистрирую материал, который можно считать универсальным знанием (т.е. разумное хорошее описание проблемы дает ответ в первой странице Google).
Для любого заинтересованного здесь мой документ prio контрольный список (работы для меня, не мог бы для Вас, комментарии и предложения высоко ценятся):
- Создайте персональный журнал/дневник, который Вы записываете все, что Вы сделали мудрую работу/знание
- Сервисы, которые - сервис то, где, что делает это и для кого это сделано (какие-либо соглашения о SLA? нужно быть создан?)
- Серверы, что - сервер то, где, какого возраста и когда записанный
- Как выше, но для сетевого оборудования, UPS и т.п.
- Как выше, но для всех пользовательских машин
- Расположение физической сети (какой кабель идет, где, какой длины это и каково измеренное качество),
- Обзор конфигурации программного обеспечения и лицензий на серверы
- Обзор конфигурации программного обеспечения и лицензий на пользовательские машины
- Обзор конфигурации переключателей, маршрутизаторов и другого выделенного оборудования
- Контракты и SLA всех сторон внешнего облика, для которых мой сервис непосредственно в зависимости от (ISP, домен и т.д.)
- Установите систему билета с интегрированной Wiki для помещения всего вышеупомянутого материала в него.
- Поскольку каждый инцидент создает тикет (даже если Вы только используете его для Вашего сам).
- Создайте сценарий, который в воскресенье собирает билеты и группирует их на проблемном типе.
- В понедельник создайте автоматическое решение или документ практического руководства конечного пользователя для большей части происходящей проблемы
- Если время разрешает, сделайте следующий.
- Если ничто больше, чтобы сделать, ищите новое задание и дайте человеку, который заменяет Вас журнал ;-)
Я довольно хорошо разбираюсь в документации. Компания, где я работаю теперь чувства, что документация важна, но некоторые люди в компании чувствуют, что у них нет времени для записи документации. Это может сделать жизнь трудной для кого-либо помимо человека, который первоначально сделал это.
Для определенных вещей я записал пошаговые инструкции. Можно назвать это контрольным списком, если Вы хотите, но он действительно не предназначается, чтобы быть физически помеченным. Я называю свой стиль документации "шагами детского сада". Это копируется после тетради MCSE я имел для одного из экзаменов Windows 2000. Шаги очень подробны, но использование полужирного/курсива/гарнитуры цвета помогает замять и просто выбрать важные части, таким образом, Вы не должны читать все после изучения шагов.
Некоторые вещи не предоставляют хорошо пошаговым инструкциям, таким образом, я пытаюсь обеспечить так данные конфигурации, как я могу. У некоторого технически склонного человека, который заканчивает тем, что поддержал в будущем, будет лучшая идея того, против чего они противостоят, и надо надеяться она сделает их жизнь немного легче, когда что-то пойдет не так, как надо.