Ho bisogno di scrivere una documentazione per gli sviluppatori per poter usare un software web API come devo creare una documentazione? Cosa dovrebbe essere sempre incluso? E deve essere davvero lungo o essere il più semplice e semplice possibile da comprendere per tutti?
Descrivi cosa fa ogni chiamata API, includi una descrizione di tutti i parametri e anche qual è il valore restituito, se presente (compresi eventuali errori / eccezioni).
Inoltre, se c'è tempo, fornisci esempi reali di come viene utilizzata la tua API, se l'API è per gli sviluppatori o se la stai trasmettendo a qualcuno che manterrà il codice un bel modo per farlo è fornendo un'unità automatizzata test che dimostrano l'uso dell'API e affermano anche che funziona correttamente.
Credo che la citazione di Einstein, "Tutto dovrebbe essere reso il più semplice possibile, ma non più semplice", si applica bene qui. Se riesci a trasmettere le tue idee in 5 pagine di testo, non c'è motivo di scrivere 50.
Un modo per farlo è impostare un sito wiki e scrivere la documentazione al suo interno. Il vantaggio è che puoi iniziare a scrivere documentazione, qualsiasi cosa ti manchi o cose non chiare, altre persone saranno in grado di correggere e aggiungere.
Nel mio team stiamo anche sperimentando l'uso di Doxygen. La parte buona è che ti fa documentare le interfacce pubbliche nel tuo codice e questo è buono anche senza la documentazione online. Ma poi genera pagine HTML che potrebbero contenere una descrizione di tutte le chiamate al metodo (simili alle sezioni "Riferimenti" nella libreria MSDN).
Tuttavia, il mio problema con Doxygen è che spesso sembra che la sezione "Reference" non sia abbastanza e tu voglia aggiungere la sezione "Using" di MSDN (e forse l'evento "About"), ma finora non ho stato in grado di capire come farlo con Doxygen. E i collegamenti che genera non sono permalink quindi non puoi avere pagine wiki che ti portano automaticamente a una pagina di riferimento specifica.
Non c'è un buon modo per far sì che Doxygen incorpori i documenti di riferimento che crea dai commenti del codice in un set di documenti più grande.
Puoi includere pagine non nell'albero dei sorgenti, ma devono essere nella cartella di esempio.
Nel mio progetto attuale creo un indice di livello superiore e includo i doxygen docs come un nodo foglia da lì, ala:
main index
/\
/ \
/ \
Guide Ref (from Doxygen)
Il bugaboo diventa quindi come creare un singolo indice con la ricerca. Ho esaminato lo zoom di Wrensoft (utilizza Php) e sembra funzionare bene. Un altro punto critico è consentire commenti per il feedback. Ho trovato qualche javascript utilizzato da uno scrittore precedente, ma richiede l'inserimento di una riga per ogni argomento / file html in un DB MySql. Non vedo alcun senso nel farlo finché i documenti non sono tranquilli.
Leggi altre domande sui tag api documentation