Вопрос: Как вы документируете свою работу, процессы и окружающую среду?


Вы используете формат wiki? Если да, то какой продукт? (MediaWiki, Confluence, Sharepoint и т. Д.)

Создаете ли вы базу знаний? (Краткие документы, ориентированные на проблемы / решения).

Какие проблемы вы обнаружите при создании документации, которая работает, так что вы не получаете звонок, когда вы в отпуске?

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

Обновить

Ответы до сих пор включают

  •  впадение
  •  Flexwiki
  •  FogBUGZ
  •  Mediawiki (с плагинами, такими как fckeditor)
  •  Sharepoint
  •  TWiki
  •  Документы Word / Excel / Visio
  •  Документированные скрипты

Редактировать: Разве вы не подразумеваете документирование своей сети с помощью вашей системы мониторинга? Nagios всегда поощрял использование родители чтобы отразить структуру вашей сети, а также notes_url директива предназначена для того, чтобы вы могли ссылаться на вики или другую документацию на основе браузера. Итак, здесь «документация» разделена между «живым документом» системы мониторинга и более подробной автономной документацией в вики. Поскольку я трачу много времени на Нагиос, имеет смысл приложить усилия к тому, чтобы сделать его максимально информативным.


48
2018-06-04 04:59


Источник


ваш вопрос только что сделал slashdot tech.slashdot.org/article.pl?sid=09/05/25/2154237 - username
hehe :) Хотел бы я как-нибудь закончить этот вопрос, возможно, дождаться, когда бета закончится ... - Cawflands
См. Раздел «Связанный» на боковой панели - serverfault.com/questions/3970/... может быть то, что вы ищете - Olaf
Системы мониторинга, такие как Nagios, сообщают вам, как выглядит ваша сеть / системы. Они обычно не говорят вам, почему сеть и системы настроены так, как они есть. - David


Ответы:


Комментирование инструментария.

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

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

Наш текущий процесс документирования:

  • статический html-генератор
  • синтаксис уценки
  • распределенная система управления версиями

У нас есть «формальный» макет документации, который предоставляет структуру для меню (и связанного с ним CSS для визуального стиля и т. Д.),

Статический генератор HTML

Мы используем встроенный статический html-генератор на основе cubictemp и ряд других инструментов: pygments, Docutils,

Сгенерированные страницы (не?) Явно уродливые, так как большинство из нас / наших системных администраторов / программистов знают, что эстетически красиво, но имеют полное отсутствие координации в создании таких.

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

Если это не HTML, просто поместите его в папку и добавьте ссылку URL-адреса.

HTML обеспечивает «потенциальную» структуру макета, а также критически обеспечивает «увязку» между элементами знаний / контента (а также механизмы базовой структуры, такие как возможность создавать меню, таблицу содержимого и т. Д.). С HTML каждый пользователь может теперь запустите на своем компьютере небольшой веб-сервер, будь то lighttpd или что-то маленькое или просто перейдете с Apache или IIS.

Все наши машины имеют хрюканье для базовой обработки html и работают достаточно хорошо для нас.

Синтаксис MARKDOWN.

Мы используем обезболиваемую версию MARKDOWN, Textish и ReStructuredText чтобы наши «творческие» соки писали документацию, не беспокоясь о HTML.

Это также означает, что каждый может использовать свой любимый редактор (я использую Scintilla для Windows и * Nix), а остальные здесь используют vi / vim.

Распределенная система управления версиями.

Мы используем Гит «распространять» документацию между пользователями. О, и мы также используем его возможности для управления версиями.

Ключевым преимуществом для нас является то, что мы все можем работать над обновлением документации без необходимости подключения к серверу и без публикации «завершенных» работ. Мы все можем работать с теми же частями документации или разными частями или просто потреблять информацию.

Лично я ненавижу привязываться к серверу, чтобы обновлять блоги, не говоря уже о вики. Git хорошо работает для нас.

Комментирование рабочего процесса

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

Лучшие решения просто заканчиваются тем, что их открывают и не требуют.


8
2018-06-04 05:55



я использую ikiwiki поверх git. Также дает мне уценку и отключенную операцию - ptman


Мы начали использовать DokuWiki где я работаю.

С сайта Dokuwiki:

DokuWiki соответствует стандартам,   простой в использовании Wiki, в основном нацеленный на   создавая документацию любого рода. Это   ориентирована на команды разработчиков,   рабочих групп и малых компаний. В нем есть   простой, но мощный синтаксис, который   гарантирует, что файлы данных остаются   читается вне Wiki и упрощается   создание структурированных текстов. Все   данные хранятся в текстовых файлах -   база данных не требуется.

Я нашел Dokuwiki самым легким в реализации, потому что он не требует базы данных, и его было легко настроить. Также были добавлены модули, которые позволили использовать мои существующие Вход в учетную запись Active Directory вместо того, чтобы создавать учетные записи для всех, что было огромным плюсом для большинства других вики-систем, которые я нашел. у него также есть типичный элемент управления версиями, где вы можете увидеть, кто разместил где и где он может, если необходимо, вернуться к предыдущей версии. Они также включают настраиваемую домашнюю страницу, где yo может легко изменить любой тип контента, который лучше всего подходит для вашей среды.


7
2018-05-04 13:31





Doku Wiki или Sharepoint для других вещей, которые вписываются в диаграмму.

Вы привыкли довольно быстро размещать на вики, и синтаксис не настолько сложный на самом деле. Очень легко организовать информацию и упростить ее поиск позже.

Я использую visio для создания графиков для более четких объяснений (экспорт в формате JPEG).


6
2018-05-04 13:53





Мы используем вики. Фактически, мы используем MediaWiki. В дополнение к MediaWiki у нас есть Расширение Semantic Mediawikiкоторый фактически превращает нашу MediaWiki в какую-то слабо типизированную базу данных, которую мы можем запросить с категорией, названием, содержимым и т. д.

Например, допустим, я хочу видеть все сетевые имена, которые проходят через Cluster F. Все, что мне нужно сделать, это использовать страницу Special: Ask для запроса [[Category: cname]] [[destination :: cluster_f]] .. и он вернет все страницы, которые классифицируются как cname с местом назначения как cluster_f.

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


6
2018-05-04 14:04





С помощью правильных плагинов, Trac может стать комбинационным билетом и вики-системой. Это облегчает для ваших билетов ссылку на статьи wiki и наоборот.

Мне нравится несколько плагинов:

  • Плагин для частных билетов, Trac построен как багбаза, где все билеты и их ответы являются общедоступными. Это не подходит для системы IT-билетов, но этот плагин исправляет это.
  • Плагин Trac WYSIWYG, Давайте посмотрим правде в глаза, большинство людей не собираются учиться wikisyntax, чтобы сделать вас счастливыми. Это дает им «то, что вы видите, то, что вы получаете» для обоих билетов и вики-страниц.

Есть немало Больше настройки для Trac. Нетрудно настроить и настроить систему Trac по своему вкусу!


6
2018-05-04 13:29



+1 это. Вики Wiki не только упрощают чтение и редактирование документации. При использовании с выпуском эмиссионных билетов и SVN для управления версиями версий у вас есть полная видимость всего рабочего процесса. - Dan Carley


В моей предыдущей работе я использовал Twiki. Он работал достаточно хорошо.

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

Сочетание обоих (и использование контроля версий для скриптов) довольно хорошо справилось.


5
2018-06-04 05:13





Сочетание документов JIRA, Confluence и Word.


5
2018-05-04 13:45





Институционализация знаний

Мы начали с документов. Затем мы сохранили некоторые из них в библиотеках Sharepoint. Затем мы перешли к вики Sharepoint. Мне нравится подход с низким коэффициентом трения wiki при быстром обновлении вещей, хотя вики WikiWatch оставляют желать лучшего в поддержке графической поддержки и форматирования для таких вещей, как таблицы. Это хорошо для текста, и встроенный редактор допускает некоторые базовые форматирования HTML и упорядоченные / неупорядоченные списки. Существуют другие недорогие альтернативы Sharepoint.

У нас также есть своя неофициальная база знаний для наших билетов поддержки в нашем справочном программном обеспечении Numara's Track-It. Это не идеально, но это работает.

Получение персонала для использования институциональных знаний

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

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

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

Было бы хорошо, если бы наша система справочной системы имела систему, похожую на StackOverflow и ServerFault: при вводе вопроса поисковая система находит похожие элементы и предлагает их, поэтому пользователи могут смотреть на них даже перед отправкой вопроса.


5
2018-06-04 05:46



+1: Где я работаю, это была аналогичная проблема с тем, чтобы заставить персонал использовать ресурсы, хотя, в частности, он использовал систему отслеживания проблем, чтобы получить проблемы. Я закончил тем, что люди, у которых возникли проблемы с изменой привычки прерывать меня на моем столе первые пару раз и заполнять новый биг с ними. Взял 2 месяца, и теперь каждый вводит свои собственные ошибки, и все они заботятся в порядке. Аналогичный подход может быть полезен здесь (т. Е. Искать соответствующий документ в [системе] с ними) - Steven Evers


В моих последних двух местах работы я использовал Wiki от Sharepoint, наряду с библиотекой документов, которая содержала определенные документы (например, DRP и однократные планы обновления), которые не могут быть легко созданы как документы Wiki. У этих документов были ссылки из Вики. Wiki имеет много преимуществ в этой области, так как многие люди могут ее редактировать, управление версиями является встроенным, легко доступным для поиска и доступным и т. Д. Чтобы быстро записать заметки или идеи, я бы использовал OneNote или доску.

Я создал базы знаний до, в формате форума (как в Lotus Notes, так и в MS Sharepoint), но я должен сказать, что только редкие люди просматривают их, чтобы увидеть, была ли решена определенная проблема. Такое решение должно исходить с одного дня с очень сильной и эффективной поисковой системой.

Если вы хотите создавать документы, которые можно использовать во время отпуска, напишите их так, как будто вы пытаетесь проинструктировать одного из своих родителей. Это не на 100% безупречно, но иногда помогает. Зависит от того, кто его читает.


4
2018-05-04 13:55



Я согласен с тем, что хороший поиск абсолютно необходим для использования этих инструментов. Совместный подход к Sharepoint был недавно достигнут коллегой, все в порядке, но это не Google. - Cawflands


Sharepoint хорош.

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

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

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

Кроме того, файлы, содержащиеся в библиотеках документов, могут быть доступны через Интернет, в Outlook или через общий доступ ко всем прямо из коробки.


4
2018-06-04 05:03