Як ви документуєте свою роботу, процеси та оточення?

Ви використовуєте формат вікі? Якщо так, то який продукт? (MediaWiki, Confluence, Sharepoint тощо)

Ви створили базу знань? (Короткі документи, орієнтовані на проблеми / рішення.)

Які проблеми ви маєте зі створенням документації, яка працює, щоб не отримати дзвінок, коли ви відпочиваєте?

Як я вважаю, часто існує певна організаційна "інертність", пов'язана з виконанням документації. Здається, це людина іншого типу, яка може виконати завдання, потім подумайте про те, як вони виконали завдання, і опишіть його, щоб хтось інший міг це зробити.

Оновлення

Досі відповіді включають

• Злиття
• Flexwiki
• Fogbugz
• Mediawiki (із плагінами, такими як fckeditor)
• Ділитися думкою
• TWiki
• Документи Word / Excel / Visio
• Задокументовані сценарії

Редагувати: Ви не неявно документували свою мережу в системі моніторингу? Nagios завжди заохочував використання директиви батьків для відображення структури вашої мережі, а директива Notes_url призначена для того, щоб ви могли посилатися на вікі або іншу документацію на базі браузера. Отже, тут "документація" розділена між "живим документом" системи моніторингу та більш детальною, офлайн-документацією у вікі. Оскільки я витрачаю багато часу, дивлячись на Nagios, є сенс докласти зусиль, щоб зробити це максимально інформативним.

Коментуючи інструментарій.

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

Підключення є серйозною проблемою, якщо ви перебуваєте в режимі офлайн або на місці (очевидно, ви можете пом'якшити місце роботи за допомогою захищеного SSL-з'єднання тощо).

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

• статичний html генератор
• синтаксис розмітки
• розподілена система версій

У нас є "формальний" макет для документації, який забезпечує структуру меню (і пов'язаний з ним CSS для візуального стилю тощо)

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

Ми використовуємо власний статичний html-генератор, заснований на cubictemp та низку інших інструментів: пігменти , документи .

Згенеровані сторінки очевидно виглядають некрасиво, оскільки більшість з нас / наших сисадмінів / програмістів знають, що естетично красиво, але цілком недостатня координація у створенні таких.

Але це дозволяє / включимо файли конфігурації, зразки скриптів, pdf тощо, не турбуючись про те, щоб форматування html викрутило його чи переймалося, де його знайти на "сервері" для завантаження.

Якщо це не HTML, просто опустіть його у папку та додайте до нього посилання url.

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

Усі наші машини мають ґрант для основного сервісу html та працює досить добре для нас.

Синтаксис MARKDOWN

Ми використовуємо базовану версію MARKDOWN, Textish і / або реструктуризованийTEXT, щоб наші «творчі» соки писали документацію, не турбуючись про HTML.

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

Розподілена система версій.

Ми використовуємо Git для "розповсюдження" документації між користувачами. О, і ми також використовуємо його ємність для версії.

Ключовою перевагою для нас є те, що ми можемо працювати над оновленням документації без підключення до сервера та без необхідності публікувати "завершені" роботи. Усі ми можемо працювати над одними і тими ж частинами документації, або різними частинами, або просто споживати інформацію.

Особисто я ненавиджу прив'язуватися до сервера, щоб оновлювати блоги, не кажучи вже про вікі. Git добре працює для нас.

Коментуючи робочий процес

Вікі, здається, є "модою" для розповсюдження / кодифікації знань, але, як це прокоментовано в інших місцях, усі процеси стають важкими для витримки, а пошук суміші інструментів, що найкраще підтримує потреби ваших команд та є стійким, потребує часу.

Кращі рішення просто виявляються і не мандат.

Ми почали використовувати DokuWiki там, де я працюю.

З веб-сайту Dokuwiki:

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

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

Doku Wiki або Sharepoint для інших речей, що входять до діаграми.

Ви досить швидко звикаєте до публікацій на вікі, і синтаксис насправді не такий складний. Організувати інформацію дуже просто і легко знайти її згодом хтось інший.

Я використовую visio, щоб робити графіки для більш чітких пояснень (експорт як JPEG).

Ми використовуємо вікі. Насправді ми використовуємо MediaWiki. Крім MediaWiki, у нас встановлено розширення Semantic Mediawiki , яке фактично перетворює наш MediaWiki на щось із невірно набраної бази даних, яку ми можемо запитувати за допомогою категорії, заголовка, вмісту тощо.

Наприклад, скажімо, я хочу переглянути всі імена мережі, які проходять через кластер F. Все, що мені потрібно зробити, - це скористатись сторінкою Special: Ask для запиту [[Категорія: ім'я]] [[призначення :: cluster_f]] .. , і він поверне всі сторінки, які класифікуються як ім'я, а пункт призначення - cluster_f.

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

За допомогою правильних плагінів Trac може стати комбінованим квитком та системою wiki. Це полегшує посилання на статті у вікі та навпаки.

Пару плагінів, які мені подобаються:

• Плагін для приватних квитків . Trac побудований як помилка, де всі квитки та їх відповіді публічні. Це не підходить для системи інформаційних квитків, але цей плагін це виправляє.
• Trac WYSIWYG плагін . Зіткнемося з цим, більшість людей не збираються вивчати вікісинтакс, щоб зробити вас щасливими. Це дає їм редактор "те, що ви бачите, те, що ви отримуєте" як для квитків, так і для сторінок вікі.

Є досить багато більш налаштувань для Trac. Не важко налаштувати та налаштувати систему Trac на свій смак!

У своїй попередній роботі я використовував Twiki. Це спрацювало досить добре.

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

Поєднання обох (і використання контролю версій для скриптів) зробило трюк досить добре.

Суміш документів JIRA, Злиття та Word.

Інституціоналізація знань

Ми почали з документами. Потім ми зберігали деякі з них у бібліотеках Sharepoint. Потім нещодавно ми перейшли до вікі Sharepoint. Мені подобається низький коефіцієнт тертя у вікі за швидке оновлення речей, хоча вікі Sharepoint залишають бажати деяких речей у графічній підтримці та підтримці форматування таких речей, як таблиці. Це добре для тексту, і вбудований редактор дозволяє деякі основні форматування HTML та упорядковані / не упорядковані списки. Існують і інші недорогі альтернативи Sharepoint.

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

Навчання персоналу до використання інституціоналізованого знання

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

Справа з цим передбачає деяке управління змінами; як і більшість успішних ініціатив щодо змін, які стосуються більше, ніж просто невеликої команди, це допоможе отримати схвалення та підтримку керівництва. Вам дійсно доведеться формувати нову поведінку у двох напрямках; комусь потрібно захоплювати знання, а людям потрібно його використовувати. Ще важче те, що людям також потрібно тримати ці дані актуальними.

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

Що було б добре, щоб у нашій службі довідкової служби була система, схожа на StackOverflow та ServerFault: під час введення запиту пошукова система знаходить схожі елементи та пропонує їх, так що користувачі можуть переглядати їх ще до того, як подавати питання.

У своїх останніх двох місцях роботи я використовував Wikipoint Sharepoint, а також бібліотеку документів, яка містила певні документи (наприклад, DRP та плани одночасного оновлення), які неможливо легко створити як документи Wiki. Ці документи мали посилання зсередини Wiki. Wiki має багато переваг у цій галузі, оскільки багато людей можуть редагувати його, вбудована версія, легко шукати та доступна тощо. Для швидкого запису приміток чи ідей я б використав OneNote або дошку.

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

Якщо ви хочете створити документи, які можна використовувати під час свят, напишіть їх так, ніби намагаєтесь доручити одному з батьків. Це не 100% нерозумність, але іноді допомагає. Залежить від того, хто її читає.

Sharepoint приємно.

Це функції пошуку мають можливість індексувати практично будь-який тип документа, що робить пошукову документацію справді простою.

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

Він також може версії ваших документів для вас, щоб у вас була історія аудиту змін документації.

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

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

Зараз ми ведемо переговори про те, щоб все перейти на MS Sharepoint , хоча і не обов'язково до їх вікі. Я думаю, що Sharepoint здатний здійснити повний пошук документів таким чином, що заперечує деякі переваги вікі, тому ми побачимо, куди це йде.

(не сподіваюсь на процес перенесення всієї нашої поточної документації :))

Ми використовуємо вікі. Звичайно, до синтаксису знадобилося трохи звикнути, але той, який ми використовуємо (twiki), повністю зберігає його дані як текстові файли. Це дозволяє нам легко читати їх у випадку катастрофи, оскільки ми можемо відновити їх у будь-якому місці та здійснити пошук у командному рядку через grep та прочитати їх у будь-якому текстовому редакторі, який нам подобається.

На кожному сервері є сторінка зі стандартною колекцією підсторінок для інформації про управління змінами, примітки щодо запуску / вимкнення та конфігурації, а також інформацію про dns, брандмауер та інформацію про об’єкти.

Ми готуємося перейти до певної версії сервісу Sharepoint, щоб спробувати відмовитись від сумісництва текстових документів, що поширюються на три сервери, і хто знає, скільки папок. Наразі у нас є масивна таблиця Excel, яка містить гіперпосилання на документи, що описані в ній.

Це не найкращий спосіб зробити це, але коли компанія почала працювати, вони ніколи не планували, як поводитися з внутрішньою документацією, і залишали її перед кожною групою, щоб вирішити, як сортувати та зберігати власну документацію так, як вони вважають за потрібне. Тепер ми намагаємося об'єднатись в єдину систему, яка буде навколо однієї з пропозицій Sharepoint.

У НУО, де я працюю, ми просто використовуємо текстові файли, поміщені в папку для критичних процедур. Особисто як гібрид системного адміністратора / веб-розробника я використовував базу знань про текстові файли, розкидані по каталогу дерев, це мій Memex, і я записую майже все на нього (особисте, робоче тощо). Цією схемою дуже просто керувати, використовуючи справжній армійський ніж для оброблення тексту Jedit , я вважав незамінним його плагін контуру, складання коду та функції гіперрозшуку. Все це безпечно підкріплено rsync на віддаленому сервері ssh-acsible.

З'єднайте це з розширенням Makelink Firefox і у вас ідеальний менеджер закладок.

Ми використовуємо flexwiki , який є точковим і відкритим кодом.

Гм ... а як щодо Фогбугза? :)

Ми використовуємо ScrewTurn для вмісту та SharePoint для зберігання документів / зображень.

Є деякі цікаві речі тут - я , як один про паролі в сейфі.

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

Як клієнти Google Apps (Enterprise), ми використовуємо виклик Google Sites - їхній wiki "смак". Простота у використанні, і ми отримали велике схвалення від адміністраторів та розробників.

Я не бачив цього питання, перш ніж я відповів на інше запитання , але ось ми йдемо.

Ми використовуємо ряд інструментів і методів.

• Функціональні характеристики для компонентів та програмного забезпечення інфраструктури.
• Дві конфігурації Вікі . Один для внутрішньої корпоративної документації (політики, процедури, внутрішня інфраструктура та ІТ тощо) та один для наших програм із відкритим кодом.
• Тести RSpec і огірок . Наше програмне забезпечення здебільшого написано на Ruby, і ми практикуємо BDD / TDD , тому тести специфікації визначають фактичний код та документ.
• Документація з вбудованим кодом. Ми використовуємо розмітку RDoc у коментарях до коду.
• Декларативне управління конфігурацією ( шеф-кухар ). Усі наші сервери управляються з шеф-кухарем, який "самостійно документує" через декаративні ресурси в рецептах та кулінарних книгах.

Нам подобається Confluence, тому що вона дуже гнучка і потужна і має повну функцію, плюс вона входить у програмне забезпечення управління квитками, яке нам подобається, Джира .

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

Це питання є дуже хорошим дублікатом цього питання, і я перенесла свою відповідь туди.

Більшу частину документації я роблю для своєї компанії, а формат, який був створений, коли я почав тут працювати, - це MS Word для редагування оригіналів, експортованих у PDF для загальних релізів, доступних лише для читання. Це досить добре працює для проектів, де лише одна людина оновлює документ, і оскільки ця людина, як правило, я, керівництво не бачило необхідності змінювати.

Ми почали документувати наші помилки та майбутні завдання з Trac , використовуючи розширення "Peer Review" для огляду коду. Це спричинило велике схвалення нашої команди, тому що в ній легко співпрацювати і легко орієнтуватися. Кілька інших членів команди висловили бажання почати більше співпрацювати зі специфікаціями, тестовими процедурами та посібниками, тому ми розглядаємо DocBook / XML, експортовані в PDF для публічної документації, як посібники, та сторінки Trac WIKI для внутрішніх документів, таких як специфікації та процедури тестування.

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

1. Це легко створити?
2. Чи легко його обслуговувати?
3. Чи легко це підтримувати, якщо хтось ще написав це?
4. Чи можна експортувати / конвертувати в інші формати без особливих клопотів?

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

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

Я відповім не системою документації, якою я користувався, а тим, що я бачив, і що мені дуже добре: http://stackexchange.com/

stackexchange - це платформа Q&A, яка працює на сервері за замовчуванням (ну, технічно це не зовсім те саме, але для нашої мети тут можна припустити, що це те саме)

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 та спільну точку доступу для документів. Я вважаю, що формат вікі в Інтернеті є кращим, коли вам потрібно дуже широко ділитися цією інформацією, і що набагато важливіше, коли документи будуть редагуватися та оновлюватися дуже часто. Тому я думаю, що статті про базу знань краще розмістити у вікі.

Зараз ми переміщуємо нашу інформацію з різних документів, розповсюджених по мережі, у два місця:

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

Для мережевих діаграм мережевий блокнот .

Також, записуючи те, що, пам’ятайте, щоб записати, чому щось налаштовано так, як є. Це допомагає не допустити, щоб ідеї, які здаються гарною ідеєю, не перетворилися на помилки.

Ми з'ясували, що MediaWiki був повільним початком, але коли люди поза межами ІТ з'ясували, як легко додавати коментарі, зміни, редагування тощо, це стає незамінним. Розробники використовують його для внутрішньої документації, відділу обладнання. для розміщення повідомлень тощо. Це означає, що це лише інструмент документації ІТ.