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

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

Вы создали базу знаний? (Проблемные / ориентированные на решение короткие документы.)

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

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

Обновить

Ответы пока включают

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Синтаксис MARKDOWN.

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

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

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

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

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

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

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

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

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

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

С сайта Докувики:

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

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

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

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

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

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

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

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

С правильными плагинами Trac может стать комбинацией тикета и вики-системы. Это позволяет вашим билетам ссылаться на вики-статьи и наоборот.

Пара плагинов, которые мне нравятся:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sharepoint это приятно.

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

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

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

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

Мы использовали MediaWiki (с fckeditor) в течение нескольких лет, хотя я должен сказать, что было бы неплохо, если бы обработка изображений (например, скриншотов) была проще. И хотя возможность поиска необходима, я считаю, что поиск в MediaWiki часто пропускает страницы. Возможно, это просто вопрос обучения лучшему поиску (что побеждает цель иметь простой способ для других выполнять вашу работу)

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

(не ожидая процесса портирования всей нашей текущей документации, хотя :))

Мы используем вики. Конечно, чтобы привыкнуть к синтаксису, потребовалось немного времени, но тот, который мы используем (twiki), сохраняет свои данные целиком в виде текстовых файлов. Это позволяет нам легко читать их в случае аварии, так как мы можем восстановить их в любом месте, искать их из командной строки через grep и читать их в любом текстовом редакторе, который нам нравится.

У каждого сервера есть страница со стандартным набором подстраниц для информации об управлении изменениями, примечаниях по запуску / выключению и конфигурации, а также DNS, брандмауэра и информации об активах.

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

Не лучший способ сделать это, но когда компания начинала, они никогда не планировали, как обращаться с внутренней документацией, и оставляли это на усмотрение каждой группы, чтобы решить, как сортировать и хранить свою собственную документацию, как они считают нужным. Теперь мы пытаемся объединиться в единую систему, которая станет частью одного из предложений Sharepoint.

В НПО, где я работаю, мы просто используем текстовые файлы, помещенные в папку, для критических процедур. Лично, как гибрид системного администратора и веб-разработчика, я использовал базу знаний текстовых файлов, разбросанных по древовидной директории, это мой Memex, и я записываю на нем почти все (личные, рабочие и т. Д.). Этой схемой очень легко управлять, используя Jedit - настоящий швейцарский армейский нож для обработки текста, я нашел его плагин структуры, свертывание кода и функции гиперзапроса незаменимыми. Все это безопасно зарезервировано rsync на удаленный ssh-доступный сервер.

Соедините это с расширением Makelink Firefox, и у вас получится отличный менеджер закладок.

Мы используем flexwiki , который является dotnet и открытым исходным кодом.

Хм ... как насчет Фогбугз? :)

Мы используем ScrewTurn для контента и SharePoint для хранения документов / изображений.

Есть некоторые интересные вещи здесь - я , как один о паролях в сейфе.

Мы используем комбинацию текстовых файлов для быстрого поиска с помощью grep. И SharePoint для более организованного сбора всесторонней документации (диаграммы Visio и т. Д.).

В качестве клиентов Служб Google (Enterprise) мы используем чертовски сайты Google - их вики "изюминку". Простота в использовании, и мы получили отличное признание от администраторов и разработчиков.

Я не видел этот вопрос, прежде чем я ответил на другой вопрос , но здесь мы идем.

Мы используем ряд инструментов и методов.

• Функциональные спецификации для компонентов инфраструктуры и программного обеспечения.
• Два слияния вики . Один для внутренней корпоративной документации (политики, процедуры, внутренняя инфраструктура и ИТ и т. Д.) И один для наших программных продуктов с открытым исходным кодом.
• Тесты RSpec и Cucumber . Наше программное обеспечение в основном написано на Ruby, и мы практикуем BDD / TDD , поэтому тесты спецификаций определяют и сам код, и документ.
• Встроенный код документации. Мы используем разметку RDoc в комментариях к коду.
• Декларативное управление конфигурацией ( Chef ). Все наши серверы управляются с помощью Chef, который «самодокументирует» с помощью изысканных ресурсов в рецептах и ​​кулинарных книгах.

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

В предыдущих компаниях, в которых я работал, я использовал множество инструментов и методов, и многие пытались использовать один универсальный ресурс (например, Wiki) для всего. Проблема с этим заключается в документировании различных тем с помощью одного инструмента, не имеющего уникального соответствия для охвата этой темы, что означает, что многие вещи не будут документированы вообще, поскольку переносить информацию сложно. Как специалист по Unix / Linux, я считаю, что для каждой задачи требуется определенный инструмент, и этот инструмент должен очень хорошо соответствовать этой задаче.

Этот вопрос очень хорошо дублирует этот вопрос, и я перенес свой ответ туда.

Я делаю большую часть документации для своей компании, и формат, который был установлен, когда я начал работать здесь, был MS Word для редактируемых оригиналов, экспортированный в PDF для общих выпусков только для чтения. Это работает довольно хорошо для проектов, где только один человек обновляет документ, и, поскольку этот человек обычно является мной, руководство не видит необходимости менять.

Мы начали документировать наши ошибки и предстоящие задачи с помощью Trac , используя расширение «Peer Review» для проверки кода. Это нашло большое признание со стороны нашей команды, потому что в ней легко сотрудничать и легко ориентироваться. Несколько других членов команды выразили желание начать больше сотрудничать со спецификациями, процедурами тестирования и руководствами, поэтому мы рассматриваем экспортированный в PDF документ DocBook / XML для публичной документации, такой как руководства, и страницы Trac WIKI для внутренних документов, таких как спецификации и процедуры испытаний.

На мой взгляд, самые большие проблемы при выборе формата документации:

1. Это легко создать?
2. Легко ли поддерживать?
3. Легко ли поддерживать, если кто-то еще написал это?
4. Можно ли экспортировать / конвертировать в другие форматы без особых хлопот?

1-3 делают мою жизнь проще и важны для быстрого создания документации без сумасшествия. Я думаю, что четвертый является самым важным для клиента, потому что форматы постоянно меняются. Формат Microsoft Word 2003 не будет вечным, как и наша текущая реализация PDF. Мне нужно убедиться, что все наши клиенты могут читать наши документы, независимо от того, какая у них ОС или программа для чтения документов.

Мы используем MediaWiki с различными плагинами, включая SemanticMediaWiki. SMW хорош, потому что он превращает нашу установку MediaWiki в большую реляционную базу данных свободной формы, которую можно запрашивать по желанию. Нужно знать, на каком сервере работает сайт? Посетите его страницу. Нужно знать, какие веб-сайты размещены на сервере? Запустите запрос, и он выберет имена страниц на основе соответствующего тега на странице каждого веб-сайта.

Я отвечу не с системой документации, которую я использовал, но с чем-то, что я видел использованным и которое я нахожу очень хорошим: http://stackexchange.com/

stackexchange - это платформа вопросов и ответов, которая работает под управлением serverfault (ну, технически это не совсем то же самое, но для нашей цели мы можем предположить, что это то же самое).

Fogbugz использует это .

Есть интересное сообщение в блоге от сотрудника Fogbugz, где я нашел эти цитаты:

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

...

С тех пор как мы начали использовать FogBugz.StackExchange.com в качестве нашей платформы поддержки, я никогда не отвечал на один и тот же вопрос дважды. У нас даже есть внутренний сервер SE, который мы используем для закрытых вопросов и ответов, и там применяются те же принципы.

Они используют stackexchange для клиентской базы знаний и внутренней базы знаний.

Мне интересно посмотреть, заменят ли такие платформы вопросов и ответов обмен знаниями на корпоративных вики.

У моего предыдущего работодателя я использовал файлы Word, Excel и Visio, собранные в одной папке. Твердая копия всего хранилась в переплете на моем столе. Я был единственным ИТ-специалистом, поэтому никто не нуждался в том, чтобы кто-то имел доступ к информации.

У моего нынешнего работодателя мы используем Macola ES от Exact Software, но я все же предпочитаю писать свою документацию в Word и загружать ее в Macola в качестве вложения, чем использовать встроенный редактор документов.

На своем рабочем месте я оставил ScrewTurn Wiki на одном из наших серверов разработки для Windows и подключил его к нашему SQL Server. Он работает очень хорошо, работает быстро и в основном не попадает под наш путь к документации. За две недели, прошедшие с момента его развертывания, мы уже добавили около 60 страниц информации, и это только для нашей команды (~ 10 человек).

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

Одной из моих любимых страниц в вики была страница с инструментами и библиотеками. Там мы начали добавлять информацию о наших любимых инструментах и ​​библиотеках, которые мы часто используем, например, grepWin для поиска текста в Windows.

Я бы полностью порекомендовал проверить всю гамму доступных вики и найти ту, которая соответствует вашему предполагаемому использованию, функциональности и среде развертывания. Я выбрал ScrewTurn, потому что он прост в использовании, и у нас было много свободного места на нашем локальном WinServer, но YMMV.

В некоторых случаях мы используем Confluence как wiki и sharepoint для документов. Я считаю, что онлайн-формат вики является предпочтительным, когда вам нужно широко распространять эту информацию, и что гораздо важнее, когда документы будут редактироваться и обновляться очень часто. Поэтому я думаю, что статьи базы знаний лучше выложить в вики.

В настоящее время мы перемещаем нашу информацию из различных документов, распространяемых по сети, в два местоположения:

1. Вики доступна в нашей интранете
2. Копия информации, относящейся к определенному серверу в этом каталоге серверов / корня.

Для сетевых диаграмм, Блокнот сети .

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

Мы обнаружили, что MediaWiki была медленным началом, но как только люди за пределами IT узнали о том, как легко было добавлять комментарии, изменения, изменения и т. Д., Это стало необходимым. Разработчики используют его для внутренней документации, отдел обслуживания. для публикации уведомлений и т. д. Это не просто инструмент для документирования ИТ.