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

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

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

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

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

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

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

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

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

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

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

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

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

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

Синтаксис MARKDOWN.

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

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

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

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

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

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

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

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

Лучшие решения просто обнаруживаются, а не требуются.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Смесь JIRA, Confluence и Word-документов.

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

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

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

Sharepoint - это хорошо.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

...

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

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

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

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

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

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

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

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

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

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

Я не видел этого вопроса, пока не ответил Другой вопрос, но поехали.

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

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

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

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

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

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

Есть кое-что интересное Вот - Мне нравится, что пароли в сейфе.

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

Эмм ... как насчет Fogbugz? :)

Мы используем flexwiki, это точка сети с открытым исходным кодом.

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

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

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

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

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

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

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

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

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

Для сетевых диаграмм Сетевой блокнот.

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

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