Ho il compito di guidare lo sforzo di documentazione per un prodotto software esistente, del tutto privo di documenti, quali risorse ci sono per aiutarmi?

Di solito uso un wiki e semplicemente spammare cose lì mentre passo attraverso il processo di scoperta. Wiki perché ottieni la ricerca e la cronologia nonché le funzioni di modifica della squadra. Lo strumento esatto è meno importante della ricerca funzionante e del fatto che tutti lo utilizzino. Aspettatevi che all'inizio sia molto approssimativo, ma incoraggiate le persone a fare quelle note ruvide mentre vanno, perché è tutto ciò che otterrete all'inizio.

Alcune cose che aiutano molto:

• avere un editor. Probabilmente, all'inizio, ma se hai il budget rendilo parte del lavoro di qualcuno. Scegli qualcuno che è bravo con il linguaggio piuttosto che un mago tecnico. Modifica per chiarezza piuttosto che perfezione: vuoi incoraggiare le persone a scrivere buoni inserimenti, ma prima dovrai guidarli.
• usa i diagrammi, ma impone che venga utilizzato uno strumento pertinente, che l'immagine sia generata e il file sorgente allegato alla pagina. In questo modo le persone possono modificare la tua immagine usando lo strumento adeguato invece di MS-Paint. Poche cose succhiano più di un diagramma veramente buono costruito in Visio per cui non si ha più il documento sorgente, solo un PNG estratto da esso.
• Incoraggiare il riarrangiamento e la modifica. Anche se all'inizio non è grandioso, hai bisogno di persone che raccolgano informazioni e correggano gli errori. I mentori devono farlo bene.
• presentati durante le riunioni settimanali della tua squadra. Prendi l'elenco delle modifiche recenti prima di entrare e elogia le persone che hanno aggiunto qualcosa di utile, poi chiedi perché quelli che non hanno, non hanno.

Ho iniziato con una immagine della macchina virtuale MediaWiki in passato perché è molto semplice e veloce iniziare , quindi le persone che dicono "è troppo difficile" non ottengono alcuna trazione iniziale.

Se la tua lingua / ambiente lo supporta utilizzando gli strumenti di tipo JavaDoc / NDoc per estrarre i commenti mentre li aggiungi è un buon approccio a basso livello. Ma è meno utile della documentazione di alto livello, e anche se gli strumenti supportano l'aggiunta di materiale di livello superiore, la creazione dal nulla utilizzando solo quegli strumenti è inutilmente laboriosa.

Se si documenta il codice stesso e non si fa la documentazione per l'utente finale, Doxygen è un ottimo strumento se i linguaggi di sviluppo sono supportati. Lo esegui sul tuo codice e crea un sito web che elenca tutte le tue funzioni, classi, ecc. Quindi puoi aggiungere commenti di codice appositamente formattati per raggruppare le cose e aggiungere ulteriori dettagli. È un ottimo modo per documentare in modo incrementale una base di codice.

Per quanto riguarda la documentazione del codice stesso, se Doxygen non soddisfa le tue esigenze, ci sono molti strumenti alternativi disponibili. Wikipedia ha una lista di quasi 50 di questi strumenti e include dettagli sulla loro funzionalità e supporto linguistico.

Dichiarazione di non responsabilità: sono associato a uno degli strumenti, Imagix 4D .

Queste sono solo alcune idee che possono essere utili a un certo livello:

Hai pensato a quale modulo prenderà questa documentazione alla fine: sarà un documento Word, un DVD, un sito con una serie di pagine che spezzerà l'applicazione, uno strumento di blogging che snocciola i dettagli dell'applicazione come ci si tuffa attraverso questo, usando un sistema di gestione dei documenti disponibile come Share Point o qualcos'altro? Ottenere risultati sarebbe un esempio di un libro online che è una serie di pagine per esempio.

Quale tipo di controllo di versione e processo di modifica vuoi che questa documentazione prenda in considerazione è un altro problema che potrebbe valere la pena di ponderare prima di arrivare troppo in là. Come vuoi gestire aggiornamenti e modifiche.

È probabile che il feedback sia un'altra dimensione interessante su questo argomento, poiché qualsiasi cosa tu crei sarà probabilmente più di alcune critiche e quanto bene tali cambiamenti saranno prioritizzati e limitati è un'altra questione che prenderei in considerazione prima di ottenere la prima versione.

Buona fortuna!

La costruzione della documentazione, come la costruzione di tutti gli altri tipi di software, è un processo intrinsecamente complesso.

Ecco perché gli sviluppatori di software hanno inventato i metodi Agile.

La documentazione è solo software senza compilatore. Gli stessi metodi per i progetti software si applicano ai progetti di documentazione. Precisamente lo stesso ragionamento.

Quando scrivi software inizi con casi d'uso (o user story). La documentazione non è diversa.

Dai la priorità ai casi d'uso con un budget approssimativo.

Hai degli sprint.

Hai versioni.

Esegui la garanzia della qualità: test, revisione, correzione e nuova versione.

È esattamente come software di sviluppo.

Chi sono i tuoi utenti? Che problemi hanno? In che modo il documento risolverà il loro problema? Dare priorità. Sprint. Alla fine, rilascerai.