Самый сложный этап создания документа - это начало. Вот простой принцип: определите четыре основных элемента документа - название, метаданные, что
и как. Создайте шаблон или план документа и заполните его разделы с начала до конца.
1. Название: простое название, понятное другим.
2. Метаданные: контактная информация автора документа - обычно ваша, дата последней редакции или история изменений. Люди, читающие документ, смогут обратиться к автору с вопросами, а когда вы получите повышение, ваши преемники будут помнить вас как человека, давшего им этот документ. Дата последней редакции и история изменений помогут людям понять, является ли документ все еще актуальным.
3. Что: предложение, описывающее содержание документа или цель, которой человек должен достичь, следуя указаниям. Достаточно одного-двух предложений.
4. Как: шаги, предпринимаемые для выполнения задачи. Для каждого шага, который может быть непонятным или запутанным, вы можете добавить почему, например «Перемотать ленту (Почему? Потому что мы выявили, что в этом случае при полном резервном копировании ошибки записи случаются реже, даже с новыми лентами»).
Затем тщательно проверьте уровень качества документа. Точность имеет очень важное значение. Опечатка или пропущенный шаг может привести к тому, что человек создаст больше проблем, чем предполагалось решить с помощью документа.
Выполните шаги, указанные в документе, самостоятельно вводя каждую команду. Затем попросите кого-нибудь другого выполнить задачу, используя документ, и предоставить вам отчет, где он встретил какие-то затруднения. Дайте человеку бумажный экземпляр, чтобы он сделал пометки, которые вы потом сможете посмотреть.
Хотя можно сделать это интерактивно, наблюдая и записывая за человеком его замечания, очень легко превратить сеанс в беседу, помогая человеку в процессе и запоминая то, что нужно будет записать потом, когда вы вернетесь за свой стол. Будьте сдержанным: если вы не позволяете человеку сделать работу самому, он не тестирует ваши инструкции. Если ваше присутствие не вызывает у человека недовольства, сядьте вне его поля зрения и наблюдайте, записывая вопросы, вызывающие затруднение.
После успешного использования этой документации несколькими сотрудниками создайте на ее основе более емкое «краткое руководство», обобщающее шаги. Это руководство просто поможет опытным системным администраторам ничего не забыть. У системных администраторов должна быть возможность вырезать и вставлять командные строки из этого документа в консоль, чтобы ускорить процесс.
Пример: два набора документации
Клифф Миллер в компании Веіі создал систему поддержки базы программного обеспечения для однородных NIX-систем. Важным элементом структуры базы было пространство имен, применяемое для различных дистрибутивов, часть которых должна быть видима только на определенных платформах или конкретных узлах. Процесс добав- ления дистрибутивов в пространство имен был немного сложным. Несмотря на то что он был подробно документирован, инструкция содержала много пояснительных данных. Это было замечательно при первом добавлении дистрибутива, но потом начинало раздражать. Решением стало создание «краткого руководства», содержавшего только необходимые для ввода команды с лаконичными пояснениями о том, что выполняется, и гипертекстовыми ссылками на соответствующий раздел полной документации. Теперь как новые, так и опытные системные администраторы могли легко выполнять процесс, пользуясь документацией в необходимом объеме.
. |
Главная
Каталог файлов
