Come gestire la documentazione funzionale?

Ci sono varie soluzioni "single source" per la documentazione là fuori. Un certo numero di team con cui ho lavorato ha avuto un grande successo con Madcap Flare . Mi piace soprattutto come si integra bene con il controllo del codice sorgente e fornisce supporto per la creazione di aiuto sensibile al contesto.

Completa divulgazione: non ho alcuna relazione con Madcap, nemmeno come rivenditore. Ma non sono mai stato così soddisfatto di un prodotto di documentazione.

In una società in cui ho lavorato ho avuto molto successo nell'usare un Wiki come repository per la documentazione tecnica. Abbiamo provato a convincere gli analisti del business dell'età della pietra a iniziare a usarlo a nostro vantaggio, ma ahimè, qualsiasi cosa che li renderebbe più responsabili di documenti obsoleti o fornire maggiore trasparenza al loro piccolo feudo è stata accolta da un'ostilità brutalmente politicizzata. / p>

Come tutte le cose anche se ne esci di ciò che ci hai messo dentro. Spazzatura nella spazzatura. Ci sono anche alcune pratiche utili che puoi prendere l'abitudine di fare, come taggare le pagine con la versione del software e creare numeri in modo da poter interrogare la storia del documento appropriata.

C'è ancora la disconnessione in quel punto in cui la versione del software viene applicata manualmente alla documentazione, in altre parole, la wiki non viene archiviata nel controllo del codice sorgente. Se sei diligente e mantieni il controllo delle versioni delle pagine nella tua wiki, aiuterai a mitigare questo problema e otterrai comunque i vantaggi di un facile accesso e modifica dei repository di documenti online.

Abbiamo utilizzato i prodotti di Atlassian. Hanno una soluzione integrata che combina JIRA, SubVersion e Confluence (Wiki).

Abbiamo applicato sharepoint per questo, ha una ricerca full text per la parola doc si integra bene in Word e in tutte le altre app di Office. Fornisce il controllo della versione e l'integrazione di explorer in modo che la gestione dei file diventi piuttosto semplice. Richiede tuttavia molte riflessioni / analisi iniziali su chi-può-accedere a cosa definire gli ambiti di ricerca, l'accesso ai documenti, ecc.

Abbiamo provato un wiki, ma per i non tecnici che in qualche modo era troppo impegnativo (specialmente la pubblicazione di immagini nel testo wiki). Se ti piace puoi mixare il wiki con la libreria documenti, sharepoint ha anche un componente wiki di base.

Abbiamo introdotto Wiki alcuni anni fa nella nostra azienda, principalmente per lo stesso scopo che hai descritto. Oggi ho sentimenti contrastanti sul successo. Ci sono alcuni ottimi articoli, e alcuni team usano bene la Wiki, ma c'è anche un sacco di spazzatura, qualcuno li ha iniziati una volta, con la nozione di "Completerò l'articolo più tardi" ma nessuno si sente responsabile per aver fatto necessario lavoro editoriale

Quindi, quando installi un Wiki, non sottovalutare lo sforzo necessario per riempire la cosa di contenuti utili. Avere qualcuno responsabile della struttura principale e per ripulire le cose. Assicurati che tutti sappiano a cosa serve il Wiki (e per cosa non dovrebbe), e parla con i tuoi dirigenti se sono disposti a rendere obbligatorio che alcune parti della documentazione commerciale debbano essere "Wiki" - solo.

It's difficult to find and update information.

Per chi?

Scherzi a parte.

There has to be a better way.

In realtà, potrebbe avere un'organizzazione buona per utenti particolari.

Altri utenti potrebbero trovarlo "difficile da trovare e aggiornare".

La cosa più importante da porsi è questa:

Chi è il pubblico?

Se hai più di un pubblico, potresti aver bisogno di documentazione in più di un luogo. Quello che hai potrebbe essere effettivamente ottimale.

Una volta che sai chi è il pubblico, devi capire chiaramente i loro casi d'uso.

Che cosa vogliono sapere?

Finché non hai definito chiaramente queste due cose, non c'è modo di scegliere tra la tua organizzazione esistente, un Wiki o - forse - meno documentazione con un focus migliore.

Dato che non hai descritto il tuo pubblico o i tuoi casi d'uso, non possiamo fornire alcun consiglio.

Abbiamo utilizzato la programmazione basata sulle funzionalità. Carichiamo tutte le funzionalità che escono dal meeting di Functional Design come Excel per Clear Quest e quindi possono essere ulteriormente collegate a Clear case code o a eventuali artefatti.

Finora negli ultimi 15 anni della mia carriera, Function Design e tracciabilità non sono mai stati così facili. Questo modello toglie tanto spreco di tempo che ho visto in altre aziende.

Fondamentalmente le nostre funzionalità sono disponibili in ClearQuest, che è facile da gestire, facile da eseguire query, facile da eseguire report sugli sforzi, arresti, facile per i manager.

Sviluppo guidato dalle funzionalità