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