Come stai documentando il tuo lavoro, i processi e l'ambiente?

Stai usando un formato wiki? In tal caso, quale prodotto? (MediaWiki, Confluence, Sharepoint ecc.)

Hai creato una base di conoscenza? (Documenti brevi orientati al problema / alla soluzione.)

Quali sfide trovi nella creazione di documentazione che funzioni, in modo da non ricevere la chiamata quando sei in vacanza?

Per me, trovo che spesso ci sia una certa "inerzia" organizzativa per ottenere la documentazione. Sembra essere un diverso tipo di persona che può svolgere un compito, quindi pensa a come ha svolto il compito e descriverlo in modo che qualcun altro possa farlo - tipo di forze per te "diventano meta" e non tutti sono a proprio agio nel farlo.

Aggiornare

Le risposte finora includono

• Confluenza
• FlexWiki
• Fogbugz
• Mediawiki (con plugin come fckeditor)
• Sharepoint
• TWiki
• Documenti Word / Excel / Visio
• Script documentati

Modifica: non stai documentando implicitamente la tua rete con il tuo sistema di monitoraggio? Nagios ha sempre incoraggiato l'uso della direttiva parent per riflettere la struttura della tua rete e la direttiva notes_url è progettata per permetterti di collegarti a una wiki o ad altra documentazione basata su browser. Quindi qui la "documentazione" è divisa tra il "documento vivente" del sistema di monitoraggio e una documentazione offline più dettagliata in un wiki. Dal momento che passo molto tempo a fissare Nagios, è logico fare uno sforzo per renderlo il più informativo possibile.

Commentando gli utensili.

Abbiamo provato i wiki online, ma abbiamo trovato una serie di limitazioni, che possono essere di gusto personale, ma includono la struttura del documento e, soprattutto, devono essere collegati al server di documentazione.

Essere connessi è un problema serio se sei offline o in loco (ovviamente puoi mitigare il sito con una connessione SSL protetta e altri).

Il nostro attuale processo di documentazione è:

• generatore html statico
• sintassi markdown
• sistema di versioning distribuito

Abbiamo un layout 'formale' per la documentazione e che fornisce la struttura per i menu (e il CSS associato per lo styling visivo ecc.)

Generatore HTML statico

Usiamo un generatore html statico interno basato su cubictemp e una serie di altri strumenti: pygments , docutils .

Le pagine generate sono (non?) Ovviamente brutte, poiché la maggior parte di noi / i nostri amministratori di sistema / programmatori sanno cosa è esteticamente bello ma hanno una totale mancanza di coordinamento nella costruzione di tali.

Ma ci consente / includiamo file di configurazione, script di esempio, pdf, ecc., Senza doversi preoccupare della formattazione html rovinandola o preoccupandoci di dove trovarla sul "server" per il download.

Se non è HTML, basta inserirlo nella cartella e aggiungere un collegamento URL ad esso.

L'HTML fornisce una struttura "potenziale" per il layout e fornisce anche un "collegamento" critico tra elementi di conoscenza / contenuto (nonché meccanismi di struttura di base, come la possibilità di creare menu, tabelle di contenuti, ecc.) Con HTML, ogni utente può ora eseguire un piccolo server Web sulla propria macchina sia lighttpd o qualcosa di piccolo o semplicemente andare in piena efficienza con Apache o IIS.

Tutte le nostre macchine hanno il grugnito per il servizio HTML di base e funzionano abbastanza bene per noi.

Sintassi di MARKDOWN.

Usiamo una versione bastardata di MARKDOWN, Textish e o reStructuredTEXT per consentire ai nostri succhi "creativi" di scrivere documentazione senza doversi preoccupare dell'HTML.

Significa anche che tutti possono usare il loro editor preferito (io uso Scintilla su Windows e * Nix) mentre gli altri qui usano vi / vim.

Sistema di controllo delle versioni distribuito.

Usiamo Git per "distribuire" la documentazione tra gli utenti. Oh, e usiamo anche la sua capacità di versioning.

Il vantaggio principale per noi è che tutti possiamo lavorare sull'aggiornamento della documentazione senza dover essere collegati al server e senza dover pubblicare lavori "completati". Tutti possiamo lavorare sulle stesse parti della documentazione o su parti diverse o semplicemente consumare le informazioni.

Personalmente, odio essere legato a un server per aggiornare blog e tanto meno wiki. Git funziona bene per noi.

Commentando il flusso di lavoro

Wiki sembra essere la "moda" per la diffusione / codificazione della conoscenza, ma come commentato altrove tutti i processi diventano difficili da sostenere e trovare il mix di strumenti che meglio supporta le esigenze dei tuoi team ed è sostenibile richiederà tempo.

Le soluzioni migliori finiscono per essere scoperte e non obbligate.

Abbiamo iniziato a utilizzare DokuWiki dove lavoro.

Dal sito Web di Dokuwiki:

DokuWiki è un Wiki conforme agli standard, semplice da usare, principalmente finalizzato alla creazione di documentazione di qualsiasi tipo. È rivolto a team di sviluppatori, gruppi di lavoro e piccole aziende. Ha una sintassi semplice ma potente che assicura che i file di dati rimangano leggibili al di fuori del Wiki e facilita la creazione di testi strutturati. Tutti i dati sono memorizzati in file di testo semplice: non è necessario alcun database.

Ho trovato Dokuwiki il più semplice da implementare perché non richiede database ed è stato facile da configurare. Ci sono stati anche moduli aggiuntivi che hanno reso possibile utilizzare i miei account di accesso Active Directory esistenti piuttosto che dover creare account per tutti, il che è stato un vantaggio enorme rispetto a molti altri sistemi wiki che ho trovato. ha anche il tipico controllo di versione, dove puoi vedere chi ha pubblicato cosa dove, e ha la possibilità di tornare facilmente a una versione precedente, se necessario. Includono anche una home page personalizzabile in cui è possibile modificare facilmente qualsiasi tipo di contenuto più adatto al proprio ambiente.

Doku Wiki o Sharepoint per altre cose che rientrano in un grafico.

Ti abitui abbastanza velocemente a pubblicare su un wiki e la sintassi non è poi così complessa. È molto facile organizzare le informazioni e renderle più facili da trovare in seguito da qualcun altro.

Uso visio per creare grafici per spiegazioni più chiare (esportazione come JPEG).

Stiamo usando un wiki. In effetti, stiamo usando MediaWiki. Oltre a MediaWiki, abbiamo installato l' estensione Semantic Mediawiki , che trasforma il nostro MediaWiki in qualcosa di un database liberamente tipizzato che possiamo interrogare con categoria, titolo, contenuto, ecc.

Ad esempio, supponiamo che io voglia vedere tutti i nomi di rete che instradano attraverso il Cluster F. Tutto ciò che devo fare è usare la pagina Speciale: Chiedi per eseguire una query [[Categoria: cname]] [[destinazione :: cluster_f]] .. e restituirà tutte le pagine che sono classificate come cname con la destinazione come cluster_f.

Supportiamo un paio di centinaia di clienti molto disparati, quindi avere quella documentazione in una posizione centrale (e averla reticolata in modo che i casi speciali rimangano documentati e legati al tutto) è una cosa estremamente utile. Ovviamente, la nostra documentazione deve essere mantenuta, ma è possibile adottare un approccio più "giardiniere" alla manutenzione perché il toolkit mediawiki per mantenere un ampio set di dati è già abbastanza maturo.

Con i plugin giusti, Trac può diventare un biglietto combinato e un sistema wiki. Ciò semplifica il collegamento dei tuoi biglietti agli articoli wiki e viceversa.

Un paio di plugin che mi piacciono:

• Plugin per biglietti privati . Trac è costruito come base di bug in cui tutti i ticket e le loro risposte sono pubblici. Questo non è appropriato per un sistema di ticket IT, ma questo plugin lo risolve.
• Trac WYSIWYG plugin . Ammettiamolo, la maggior parte delle persone non imparerà il wikisyntax per renderti felice. Questo dà loro un editor 'quello che vedi è quello che ottieni' sia per i biglietti che per le pagine wiki.

Ci sono alcune altre personalizzazioni per Trac. Non è difficile configurare e personalizzare un sistema Trac a proprio piacimento!

Nel mio lavoro precedente ho usato Twiki. Ha funzionato abbastanza bene.

Accanto a ciò, tendo ad automatizzare la maggior parte delle attività e documentare gli script (non sempre con molto entusiasmo, ma comunque ...). Documentare gli script è facilmente eseguibile nel processo di progettazione, quindi nessun vero sovraccarico ...

La combinazione di entrambi (e l'utilizzo del controllo versione per gli script) ha funzionato abbastanza bene.

Un mix di documenti JIRA, Confluence e Word.

Istituzionalizzazione della conoscenza

Abbiamo iniziato con i documenti. Quindi ne abbiamo archiviati alcuni nelle librerie di Sharepoint. Quindi recentemente ci siamo spostati sul wiki di Sharepoint. Mi piace l'approccio a basso attrito del wiki nell'aggiornamento rapido delle cose, anche se i wiki di Sharepoint lasciano alcune cose a desiderare nel supporto grafico e nel supporto di formattazione per cose come le tabelle. Va bene per il testo e l'editor integrato consente una formattazione HTML di base e liste ordinate / non ordinate. Esistono altre alternative a basso costo a Sharepoint.

Abbiamo anche una sorta di knowledge base informale per i nostri ticket di supporto nel nostro software di help desk, Track-It di Numara. Non è perfetto ma funziona.

Chiedere al personale di utilizzare la conoscenza istituzionalizzata

Concordo con la tua valutazione sul fatto che ottenere la conoscenza istituzionalizzata sia solo una parte della battaglia. Se la tua organizzazione e le persone non sono abituate alla "ricerca prima, chiedi poi", allora scoprirai che prevale il vecchio modo: tutti cercheranno ancora risposte ai guru formali e informali, e per alcune persone sarà sempre più facile chiedere la persona accanto a te che cercare da solo.

Affrontare questo richiederà una certa gestione del cambiamento; come la maggior parte delle iniziative di cambiamento di successo che interessano più di un semplice team, aiuterà ad avere supporto e supporto manageriale. Devi davvero forgiare un nuovo comportamento in due direzioni; qualcuno deve acquisire le conoscenze e le persone devono usarle. Ancora più difficile è che le persone debbano anche mantenere tali dati aggiornati.

Solo alcune idee: probabilmente ci sarà bisogno di incoraggiamento sotto forma di una politica formale che affermi che i biglietti e i problemi risolti devono essere documentati nella knowledge base o nella wiki prima che possano essere considerati chiusi. Inoltre, i leader della conoscenza che normalmente ricevono domande non dovrebbero sempre offrire risposte solo su richiesta; devono indirizzare le persone verso i wiki e abituarli a controllare prima lì. Un'altra cosa sarebbe rendere i dati disponibili agli utenti per l'auto-aiuto in modo che il problema potesse essere potenzialmente risolto prima che diventasse un altro elemento che lo staff tecnico deve destreggiarsi.

La cosa interessante sarebbe che il nostro sistema di help desk avesse un sistema simile a StackOverflow e ServerFault: quando si digita una domanda, il motore di ricerca trova elementi simili e li offre, in modo che gli utenti possano guardarli anche prima di inviare la domanda.

Nei miei ultimi due posti di lavoro ho usato il Wiki di Sharepoint, insieme a una libreria di documenti che conteneva alcuni documenti (come DRP e piani di aggiornamento una tantum) che non possono essere facilmente creati come documenti Wiki. Quei documenti avevano collegamenti all'interno del Wiki. Wiki ha molti vantaggi in questo settore, poiché molte persone possono modificarlo, il versioning è integrato, facilmente ricercabile e accessibile, ecc. Per scrivere rapidamente note o idee, utilizzare OneNote o una lavagna.

In precedenza avevo creato alcune basi di conoscenza, in formato forum (sia in Lotus Notes che in MS Sharepoint), ma devo dire che solo raramente le persone le guardano per vedere se un certo problema è già stato risolto. Tale soluzione deve venire fin dal primo giorno con un motore di ricerca molto forte ed efficace.

Se vuoi creare documenti che possono essere utilizzati mentre sei in vacanza, scrivili come se stessi cercando di istruire uno dei tuoi genitori. Questo non è sicuro al 100%, ma a volte aiuta. Dipende da chi lo sta leggendo.

Sharepoint è carino.

Le sue funzionalità di ricerca hanno la capacità di indicizzare quasi ogni tipo di documento, rendendo la ricerca della documentazione davvero semplice.

Può anche fare un po 'di template che può rendere le cose più facili se, ad esempio, hai una scheda informativa standard per ogni server che costruisci.

Può anche eseguire la versione dei documenti per te in modo da avere una cronologia di controllo delle modifiche alla documentazione.

Inoltre, è possibile accedere ai file contenuti nelle raccolte documenti sul Web, in Outlook o tramite una condivisione non standard.

Abbiamo usato MediaWiki (con fckeditor) per diversi anni, anche se devo dire che sarebbe bello se la gestione delle immagini (cioè degli screenshot) fosse più semplice. E pur avendo la capacità di cercare è essenziale, trovo che la ricerca di MediaWiki spesso non raggiunga le pagine. Forse è solo questione di imparare a cercare meglio (che tipo di sconfitte ha lo scopo di avere un modo semplice per gli altri di fare il tuo lavoro)

In questo momento stiamo parlando di spostare tutto su MS Sharepoint , anche se non necessariamente nella loro wiki. Penso che Sharepoint sia in grado di eseguire ricerche complete di documenti in un modo che annulli alcuni dei vantaggi di un wiki, quindi vedremo dove andrà.

(non vedo l'ora di eseguire il porting di tutta la nostra documentazione attuale :))

Stiamo usando un wiki. Sicuramente la sintassi ha richiesto un po 'di tempo per abituarsi, ma quella che stiamo usando (twiki) memorizza i suoi dati interamente come file di testo. Questo ci consente di leggerli facilmente in caso di disastro, in quanto possiamo ripristinarli ovunque, cercarli dalla riga di comando tramite grep e leggerli in qualsiasi editor di testo che ci piace.

Ogni server ha una pagina, con una raccolta standard di pagine secondarie per informazioni sulla gestione delle modifiche, avvio / arresto e note di configurazione, nonché informazioni su DNS, firewall e risorse.

Ci stiamo preparando a passare a una versione di un servizio Sharepoint per cercare di farci uscire da una combinazione di documenti Word distribuiti su tre server e chissà quante cartelle. Attualmente, abbiamo un enorme foglio di calcolo Excel che contiene collegamenti ipertestuali ai documenti che sono descritti in esso.

Non è il modo migliore per farlo, ma quando la società ha iniziato, non hanno mai pianificato come gestire la documentazione interna e lo hanno lasciato a ciascun gruppo per decidere come ordinare e archiviare la propria documentazione come ritenuto opportuno. Ora stiamo provando a fonderci in un sistema unificato, che sarà intorno a una delle offerte di Sharepoint.

Nella ONG in cui lavoro utilizziamo solo file di testo inseriti in una cartella per le procedure critiche. Personalmente come un ibrido di amministratore di sistema / sviluppatore web ho usato una base di conoscenza di file di testo sparsi su una directory ad albero, questo è il mio Memex e ho scritto quasi tutto su di esso (personale, lavoro, ecc.). Questo schema è molto facile da gestire usando Jedit, un vero coltellino svizzero per l'elaborazione del testo, ho trovato indispensabili i suoi plug-in di contorno, la piegatura del codice e le funzionalità di ricerca di ipersearch. Tutto questo è stato eseguito il backup sicuro di rsync su un server remoto accessibile tramite ssh.

Coppia che, con il Makelink Firefox Extension e si ha la perfetta gestione dei segnalibri.

Usiamo flexwiki , che è un dotnet e open source.

Ehm ... che ne dici di Fogbugz? :)

Stiamo usando ScrewTurn per contenuti e SharePoint per archiviare documenti / immagini.

Ci sono alcune cose interessanti qui - mi piace quella sulle password in una cassaforte.

Usiamo una combinazione di file di testo per una rapida ricerca con grep. E SharePoint per una raccolta più organizzata di documentazione approfondita (diagrammi di Visio, ecc.).

Come clienti di Google Apps (Enterprise), usiamo il controllo di Google Sites - il loro "sapore" wiki. Facile da usare e abbiamo avuto un'ottima adozione da amministratori e sviluppatori.

Non ho visto questa domanda prima di rispondere a un'altra domanda , ma eccoci qui.

Utilizziamo numerosi strumenti e metodi.

• Specifiche funzionali per componenti e software dell'infrastruttura.
• Due wiki di confluenza . Uno per la documentazione aziendale interna (politiche, procedure, infrastruttura interna e IT, ecc.) E uno per i nostri prodotti software open source.
• Test RSpec e Cucumber . Il nostro software è principalmente scritto in Ruby e pratichiamo BDD / TDD , quindi i test di specifica guidano il codice reale e documentano pure.
• Documentazione del codice in linea. Usiamo il markup RDoc nei commenti sul codice.
• Gestione della configurazione dichiarativa ( Chef ). Tutti i nostri server sono gestiti con Chef, che "auto documenta" attraverso risorse delcarative in ricette e libri di cucina.

Confluence ci piace perché è molto flessibile, potente e completo di funzionalità, inoltre si lega al software di gestione dei biglietti che ci piace, Jira .

Nelle aziende precedenti in cui ho lavorato, ho usato una varietà di strumenti e metodi e molti hanno cercato di rimanere con una sola risorsa (come un Wiki) per tutto. Il problema è quello di documentare vari argomenti con un unico strumento non adatto in modo univoco alla copertura di quell'argomento significa che molte cose non verranno affatto documentate, perché è difficile migrare le informazioni. Come un fanatico di Unix / Linux, credo che ogni compito richieda uno strumento specifico e che lo strumento dovrebbe adattarsi a quel compito estremamente bene.

Questa domanda è benissimo un duplicato di questa e ho spostato la mia risposta lì.

Faccio la maggior parte della documentazione per la mia azienda, e il formato che è stato stabilito quando ho iniziato a lavorare qui era MS Word per originali modificabili, esportati in PDF per versioni generali di sola lettura. Funziona abbastanza bene per i progetti in cui solo una persona sta aggiornando il documento e dato che quella persona di solito sono io, la direzione non ha visto la necessità di cambiare.

Abbiamo iniziato a documentare i nostri bug e le attività imminenti con Trac , mentre utilizzavamo un'estensione "Peer Review" per le revisioni del codice. Ciò ha visto una grande accettazione da parte del nostro team perché è semplice collaborare ed è facile da navigare. Alcuni altri membri del team hanno espresso il desiderio di iniziare a collaborare maggiormente con specifiche, procedure di test e manuali, quindi stiamo esaminando DocBook / XML esportato in PDF per documentazione pubblica come manuali e pagine Trac WIKI per documenti interni come specifiche e procedure di prova.

Nella mia mente, i maggiori problemi nella scelta di un formato di documentazione sono:

1. È facile da creare?
2. È facile da mantenere?
3. È facile da mantenere se qualcun altro lo ha scritto?
4. Può essere esportato / convertito in altri formati senza troppi problemi?

1-3 mi semplificano la vita e sono importanti per produrre rapidamente la documentazione senza impazzire. Penso che il quarto sia il più importante per il cliente, perché i formati cambieranno continuamente. Il formato di Microsoft Word 2003 non sarà disponibile per sempre, né la nostra attuale implementazione di PDF. Devo assicurarmi che tutti i nostri clienti possano leggere i nostri documenti, indipendentemente dal loro sistema operativo o lettore di documenti preferito.

Usiamo MediaWiki con vari plugin, incluso SemanticMediaWiki. SMW è piacevole perché trasforma la nostra installazione di MediaWiki in un grande database relazionale in formato libero che può essere interrogato a piacimento. Hai bisogno di sapere su quale server si trova un sito Web? Visita la sua pagina. Hai bisogno di sapere quali siti Web sono ospitati su un server? Esegui una query e selezionerà i nomi delle pagine in base al tag corretto sulla pagina di ciascun sito Web.

Risponderò non con un sistema di documentazione che ho usato, ma con qualcosa che ho visto usato e che trovo molto buono: http://stackexchange.com/

stackexchange è la piattaforma di domande e risposte che funziona sotto serverfault (beh, tecnicamente non è esattamente la stessa cosa, ma per il nostro scopo qui possiamo supporre che sia la stessa).

Fogbugz lo usa .

C'è un interessante post sul blog di un dipendente di Fogbugz dove ho trovato queste citazioni:

A tutti gli effetti, al di fuori delle specifiche del prodotto, penso che le wiki aziendali e i moduli di discussione siano stati sottoposti a un duro colpo.

...

Da quando abbiamo iniziato a utilizzare FogBugz.StackExchange.com come piattaforma di supporto, non ho mai risposto alla stessa domanda due volte. Abbiamo anche un server SE interno che utilizziamo per domande e risposte non pubbliche e gli stessi principi si applicano lì.

Usano stackexchange per la knowledge base rivolta al cliente e la knowledge base interna.

Sono interessato a vedere se tali piattaforme di domande e risposte di scambio di conoscenze sostituiranno le wiki aziendali.

Nel mio precedente datore di lavoro ho usato i file Word, Excel e Visio raccolti insieme in una cartella. Una copia cartacea di tutto era conservata in un raccoglitore nella mia scrivania. Ero l'unica persona IT quindi non c'era bisogno che chiunque avesse accesso alle informazioni.

Al mio attuale datore di lavoro utilizziamo Macola ES di Exact Software, ma preferisco ancora scrivere la mia documentazione in Word e caricarla in Macola come allegato piuttosto che utilizzare l'editor di documenti integrato.

Nel mio posto di lavoro, ho scaricato ScrewTurn Wiki su uno dei nostri server di sviluppo Windows e l'ho collegato al nostro SQL Server. Funziona davvero bene, funziona rapidamente e principalmente rimane fuori dalla nostra strada per la documentazione. Nelle due settimane successive alla distribuzione, abbiamo già aggiunto circa 60 pagine di informazioni, ed è solo per il nostro team (~ 10 persone).

Finora, manteniamo informazioni sui progetti attuali e passati e abbiamo iniziato ad aggiungere informazioni sulle applicazioni come come costruirle da zero, URL e altre informazioni importanti per i nuovi sviluppatori del team.

Una delle mie pagine preferite sul wiki è stata la pagina degli strumenti e delle librerie. Lì, abbiamo iniziato ad aggiungere informazioni sui nostri strumenti e librerie di produttività preferiti che usiamo molto, un esempio dei quali è grepWin per la ricerca di testo in Windows.

Consiglio vivamente di dare un'occhiata alla gamma completa di wiki disponibili e di trovarne uno adatto all'utilizzo, alla funzionalità e all'ambiente di distribuzione previsti. Ho scelto ScrewTurn perché è facile da usare e avevamo un sacco di spazio libero sul nostro WinServer locale, ma YMMV.

In alcuni casi stiamo usando Confluence come wiki e sharepoint per i documenti. Credo che il formato wiki online sia preferibile quando è necessario condividere queste informazioni in modo molto ampio e ciò che è molto più importante quando i documenti verranno modificati e aggiornati molto spesso. Quindi penso che gli articoli della knowledge base siano meglio inserire nel wiki.

Attualmente stiamo trasferendo le nostre informazioni da vari documenti sparsi nella rete in due posizioni:

1. Una wiki disponibile sulla nostra intranet
2. Una copia delle informazioni relative a un determinato server in quella directory server / root.

Per gli schemi di rete, Blocco note di rete .

Inoltre, durante la registrazione del cosa, ricordati di registrare perché qualcosa è configurato come è. Questo aiuta a impedire che idee che sembrano una buona idea si trasformino in errori.

Abbiamo scoperto che MediaWiki è stato un avviatore lento, ma una volta che persone al di fuori dell'IT hanno capito quanto fosse facile aggiungere commenti, modifiche, modifiche ecc., È diventato indispensabile. Gli sviluppatori lo utilizzano per la documentazione interna, il reparto strutture. per la pubblicazione di avvisi, ecc. È cresciuto oltre ad essere solo uno strumento di documentazione IT.