TL:DR? Ладно...вот:
Помимо найма или аутсорсинга технического писателя, существуют ли базовые стандарты/конвенции/практики, которые технические писатели применяют в своей работе и которым можно научиться, чтобы создавать надлежащую ИТ-документацию и поддерживать ее в актуальном состоянии?
При написании различной документации как для внутреннего использования ИТ-отделом, так и для внешнего использования нашими сотрудниками стало ясно, что у каждого из них есть свой собственный стиль в отношении документации.
Используя наши документы по качеству и контролируемую документацию, ИТ-отдел использовал различные шаблоны для стандартных операционных процедур, рабочих процессов и различных форм, используемых для документов по качеству ИТ. Эти документы, хотя и не обязательно полезны для повседневной работы в ИТ, помогают сотрудникам и компании решать кадровые вопросы ИТ, вопросы соответствия и т. д. и обычно хорошо написаны, четко определены и следуют, по крайней мере, шаблонам и стандартам документации отдела качества (таким как управление версиями, ECN и т. д.)
Однако в написании наших ИТ-документов по-прежнему отсутствует настоящий стандарт/концепция. Некоторые используют сторонние инструменты, такие как ScreenSteps, другие просто используют Word и создают простую схему, например:
- Открыть
app- Нажмите «Начать глобальную термоядерную войну»
- ...
- Выгода
Внутренняя ИТ-документация на самом деле хуже, основанный на том, что сотрудник или консультант считал достаточным в то время, чтобы либо подстегнуть свои собственные воспоминания, либо основывался на их редакторе по выбору (vi, word, excel, powerpoint, Napple, внутренняя wiki). Проблема возникает, когда сотрудник уходит или находится в отпуске, и приходится суетиться, чтобы выяснить даже основную информацию. Иногда только дата файла может служить показателем того, актуальны ли данные или нет.
Хотя простой план, настоящие скриншоты или даже полноценное видео в формате HD — это, конечно, хорошо, у нас в штате нет настоящего технического писателя по ИТ, и мы не можем не думать, что нам не хватает специалистов в этой области.
Можем ли мы создать собственные стандарты для нашей документации вместе с утвержденными шаблонами? Да, но зачем изобретать велосипед? Если такие стандарты и соглашения уже существуют в «гильдии» технических писателей, нам было бы лучше следовать этим соглашениям, чтобы наша документация была ясной, краткой и профессиональной.
Чтобы избежать того, чтобы мне сказали"Погугли это", я посмотрел сайты, на которых показаны некоторые приемы форматирования, и хотя этот вопрос SF:Платформы ИТ-документациипомогает в поиске платформ и программного обеспечения для обработки текста, но не обсуждает, существуют ли на самом деле стандарты в отрасли.
Итак, помимо найма или аутсорсинга технического писателя, существуют ли базовые стандарты/конвенции/практики, которые технические писатели применяют в своей работе и из которых можно извлечь уроки, чтобы создавать надлежащую ИТ-документацию и поддерживать ее в актуальном состоянии?
решение1
Писательство — это дисциплина.
Я много чего сделал, и у меня есть столько основ, сколько может получить неподготовленный человек, не имея документации как основной части моей работы. Время показало мне, какую документацию я создаю, действительно будут читать, а что отправится на Полку Вечного TL;DR. Это на самом деле правило номер один при написании чего угодно:
Знайте свою аудиторию.
Аудитория внутренней ИТ-документации — это мы сами. А системные администраторы? Когда мы беремся за документацию, особенно внутреннюю, мы ищем:
- Обнаруживаемый
- Краткий
- К точке
- Доставляет меня туда, куда я направляюсь.
Объяснение в пять абзацев на фоне системы будет проигнорировано в пользу контрольного списка под ним, потому что мы торопимся и нам просто нужно это сделать. И если предупреждение там, чтоесли вы выполните определенные шаги не в том порядке, все ваши резервные копии будут удалены.находится в этом пропущенном блоке текста, возможно, его следует отформатировать, чтобы привлечь внимание, или, может быть, включить этот фрагмент в контрольный список.
Документация процесса
Этот тип документации посвящен описанию способа выполнения чего-либо. Это самый простой способ для неподготовленного человека, поскольку в основном это просто запись последовательности шагов, которым нужно следовать. По моему опыту, хорошая документация процесса имеет следующие характеристики:
- Содержит контрольный список.
- Контрольный список находится на той же странице, что и краткое описание того, когда и почему он используется.
- Под контрольным списком или на связанной странице находится более подробный документ, описывающий теорию, лежащую в основе контрольного списка, и возможные варианты.
Вам нужно, чтобы на странице был контрольный список, которому нужно следовать, и хотя бы первый уровень шагов по устранению неполадок (или в одном клике), если они понадобятся.
Это знакомый формат, если вы когда-либо просматривали статьи Microsoft KB: резюме, исправление, подробности, затронутые системы. На это есть причина.
Руководства по устранению неполадок
Это сложнее, чем документация процесса, потому что вам нужно кодировать деревья решений в вашей документации. Простого контрольного списка, вероятно, будет недостаточно, но разветвленный контрольный список, который использует ссылки на другие контрольные списки, вполне выполним. Те же правила применяются к этому виду документации, что и к документации процесса:
- Будьте кратки, не перегружайте читателя подробностями.
- Четко определите, на каких этапах необходимо принимать решения и куда следует направить дальнейшие действия.
- Подробные технические сведения оставьте для архитектурной документации.
Руководство по устранению неполадок может представлять собой большую историю «Выбери свое собственное приключение» или большой маркированный список всех неполадок в системе и способов их устранения.
Архитектурная документация
Самый сложный в изготовлении тип, поскольку он предназначен как справочный материал, к которому будут обращаться только новички, желающие разобраться в сложной теме, с которой они только что столкнулись.
Архитектурная документация — это документ «почему». Это то, почему используется эта система, а не та, как они связаны с этой другой системой и что заставило эту связь работать так, как она работала. Это документация, которую вы должны написать, как только узнаете, как выглядит ваша производственная конфигурация, и обновлять ее по мере внесения изменений.
Что касается формата, то здесь мне придется довериться экспертам.
Хорошая документация — это не просто шаблон и формат, единый внешний вид хорош и улучшает читабельность, но нужны и некоторые другие вещи.
Регулярные обновления
Возьмите за привычку просматривать документацию, которая у вас уже есть, чтобы убедиться, что она все еще хороша. Контрольный список для версии 1.17 может не подойти для версии 1.26, пора обновить его. Механические контрольные списки нуждаются в наибольшем обновлении, поскольку даже самые незначительные изменения пользовательского интерфейса могут все испортить.
Посвятив 10 минутнеделядо просмотра документации и выявления моментов, требующих доработки, может творить чудеса.
Архитектурная документация должна периодически просматриваться тем, кто знает систему. Как я уже упоминал, это редко используемые документы, но очень полезные, когда они вам действительно нужны. Вам не нужен документ, описывающий, как кластер обслуживания печати кампуса соединен с NetWare, когда миграция на Windows произошла 3 года назад.
Обнаруживаемый
Это самое трудное для понимания, потому что это во многом зависит отгдевы храните свою документацию.
Что мы говорим любому, кто приходит в ServerFault с вопросом?
Что вы уже попробовали?
Вскоре после этого последовало
Топ-хит в Google решает вашу проблему. Может быть, вам стоит попробовать это.
Мы ищем нашу документацию, мы не идем к книжной полке. Репозиторий документации должен быть таким же поисковым, как Google, или мы просто пойдем в Google.
Central Napkin Repository — плохое место для документации, по крайней мере, если у него нет онлайн-индекса (а его не будет). Лучше использовать простую вики, поскольку большинство из них включают хотя бы базовый текстовый поиск. Лучшая система — та, которая позволяет искать по тегам в дополнение к полному тексту, чтобы лучше сфокусировать поиск на целевых областях.
Если вы работаете с хранилищем документов, которое поддерживает теги,стандартизируйте свои теги. Просто посмотрите на список тегов ServerFault иногда, чтобы понять, почему. Пользователи не должны запоминать восемь перестановокvmwareпросто чтобы найти то, что они ищут. Это потребует периодических усилий по перемаркировке.