Lista di controllo Ambiente software Documentazione [chiusa]

Question

Io lavoro per una compagnia di assicurazioni. Abbiamo il nostro reparto di sviluppo made-up di quasi 150 persone, più alcuni provider (di outsourcing e applicazioni su misura più o meno). Nella nostra società la mia squadra hanno fatto ciò che noi chiamiamo librerie logiche non funzionali. Cioè, librerie software per gestire le cose che sono orizzontali a tutti i team di sviluppo nel nostro reparto, per esempio Sicurezza, Webservices, registrazione, messaggistica e così via. La maggior parte di questi strumenti o siano stati fabbricati con zero o l'adattamento di uno standard de-facto. Per esempio il nostro logger è un appender basata su Log4J che salva anche i messaggi di registrazione in un database. Definiamo anche ciò che le biblioteche di utilizzare l'applicazione, ad esempio, che quadro per webservices da usare. Noi usiamo praticamente JavaEE e Oracle AS in tutta la nostra organizzazione (con alcune WebSphere Application Server).

Gran parte di questi progetti hanno la loro architettura documentato (casi d'uso, diagrammi UML, ecc) e in generale la documentazione generata sono disponibili. Ora quello che abbiamo visto è che per gli utenti a volte è difficile da usare le biblioteche che forniamo e sono costantemente chiedono domanda o semplicemente non vengono utilizzati.

Quindi, stiamo progettando di generare una documentazione più accogliente per loro, quindi la mia domanda è: Quali sono le migliori pratiche o la lista di controllo che la documentazione del software dovrebbe avere?

Qualcosa mi viene in mente:

1. guida API Reference
2. Avvio rapido tutorial
3. API documentazione generata.
4. Deve essere ricercabile
5. Web Access

Che altro dovrebbe avere? Inoltre, sulla base della tua esperienza qual è il modo migliore per mantenere (mantenere up-to-date) e pubblicare questo tipo di documentazione?

Answer 1

Conservare la documentazione in controllo di versione anche.

Assicurati che in ogni pagina ha un numero di versione in modo da sapere dove l'utente ha letto da.

Ottenere un server CI andare e spingere la documentazione per un sito di documentazione DIRETTA su aggiornamenti.

Fare recensioni di documentazione come si farebbe codificare le recensioni.

Dog-cibo che:)

La gentilezza,

Dan