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

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

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

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

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

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

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

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

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

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

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

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

Но это предоставляет/давайте нам, включают конфигурационные файлы, демонстрационные сценарии, PDF, и т.д., не имея необходимость волноваться о форматировании HTML, завинчивающем его или вызывающем беспокойство о том, где найти его на 'сервере' для загрузки.

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

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

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

Синтаксис СКИДКИ С ЦЕНЫ.

Мы используем ухудшаемую версию СКИДКИ С ЦЕНЫ, Textish и или reStructuredTEXT, чтобы позволить нашим 'творческим' сокам записать документацию, не имея необходимость волноваться о HTML.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Получение штата использовать узаконенный Knowlege

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

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

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

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

Соединение JIRA, Слияния и Word Documents.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Существуют некоторые интересные вещи здесь - мне нравится тот о паролях в сейфе.

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

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

С веб-сайта Dokuwiki:

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

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

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

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

• Функциональные спецификации для компонентов инфраструктуры и программное обеспечение.
• Два Слияния Wikis. Один для внутренней корпоративной документации (политики, процедуры, внутренняя инфраструктура и IT, и т.д.) и один для наших продуктов программного обеспечения с открытым исходным кодом.
• RSpec и Огуречные тесты. Наше программное обеспечение главным образом записано в Ruby, и мы практикуем BDD/TDD, таким образом, тесты спецификации управляют фактическим кодом и документом также.
• Документация встроенного кода. Мы используем разметку RDoc в комментариях к коду.
• Декларативное управление конфигурацией (Шеф-повар). Всеми нашими серверами управляют с Шеф-поваром, который "сам документы" через декларативные ресурсы в рецептах и поваренных книгах.

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

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

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

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

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

В моем уме самые большие проблемы при выборе формата документации:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Частный плагин Билетов. Trac создается как bugbase, где все билеты и их ответы общедоступны. Это не соответствует системе билета IT, но этот плагин фиксирует это.
• Trac плагин WYSIWYG. Давайте столкнемся с ним, большинство людей не собирается изучать wikisyntax для создания Вас счастливыми. Это дает им '"что видишь, то и получишь"' редактор для обоих билетов и страниц Wiki.

Существует еще довольно много настроек для Trac. Не трудно установить и настроить систему Trac к Вашей симпатии!

Sharepoint хорош.

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

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

Это может также присвоить версию Вашим документам для Вас так, у Вас есть контрольная история изменений документации.

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

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

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

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

Пара, что с Расширением Firefox Makelink и у Вас есть идеальный менеджер закладок.

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

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

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

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

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

...

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

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

Мне интересно видеть, заменят ли такие платформы Вопросов и ответов обмена знаний корпоративную Wiki.