Esiste una gestione della documentazione API?

Question

Esiste una gestione della documentazione API?

#1 da (2 voti)
#2 da (1 voti)

1

Quindi ho iniziato a pensare, qual è la best practice per la pubblicazione di documentazione generata (ad esempio Doxygen, NaturalDocs, ecc.) in termini di infrastruttura?

Lo genererei attraverso l'integrazione continua:

Dovrebbe essere inserito in un normale web server? o dovrei usare qualcosa come Sharepoint o qualche altro software di content publishing?
La documentazione dovrebbe essere disponibile per ogni build? o solo versioni stabili
Devo inserire una copia completa di ciascuna iterazione della documentazione? o devo inserirla nel controllo della versione sovrascrivendo se stesso? (un repository separato dal codice del progetto, ovviamente)

Per qualche strana ragione trovo difficile pensare che dovrei semplicemente metterlo in un server abilitato al web, ma questo è il modo in cui vedo che la maggior parte lo fa:

link

Tuttavia, cosa succede quando la tua azienda lavora su decimi se non su centinaia di progetti ?, la maggior parte degli strumenti di generazione di documentazione AFAIK ti fornisce l'output HTML finale, ma spetta a te gestirlo.

Quindi, che cosa ?, c'è una soluzione / soluzione migliore rispetto al semplice inserimento nel "doc server"?

continuous-integration documentation-generation

posta dukeofgaming 18.06.2014 - 08:25

fonte

2 risposte

Leggi altre domande sui tag continuous-integration documentation-generation

Sviluppo software basato su un'implementazione di riferimento [chiuso] Comprensione dell'aritmetica in C

score 2 · Answer 1

Un altro modo di pensarlo non è un "doc server", ma quello che stai creando un "Portale per sviluppatori" per il tuo pubblico che consuma API. Questo potrebbe includere sviluppatori, ma potrebbe anche includere product manager, utenti UI / UX, analisti aziendali, ecc.

Alcune cose che un Portale per gli sviluppatori potrebbe esporre, oltre alla semplice documentazione grezza includono:

Codice di esempio
App di esempio
Wrappers / librerie specifiche della lingua
Esercitazioni
Supporto di forum, biglietteria e altri mezzi per contattare i produttori di API

Stripe / docs è un eccellente esempio di esposizione di questi tipi di risorse insieme alla documentazione: link

L'aggiunta di queste cose va oltre la semplice verifica della disponibilità di documenti, a fare il massimo che puoi per creare una grande esperienza per gli sviluppatori che lavorano con le tue API. Consideralo come "usabilità", non nel senso della UI, ma è ciò che serve a qualcuno per essere aggiornato e avere successo con le tue API come prodotto.

score 1 · Answer 2

Proprio così - gli strumenti documentali che producono HTML dovrebbero essere messi su un server web. Se hai molti progetti, copia l'output html in sottodirectory e aggiorna una pagina indice principale che si collega a ciascuno di essi. Puoi mettere un link alla "pagina iniziale" di ciascun progetto in un wiki per ogni progetto (se usi un sito di gestione del progetto come redmine o trac).

Il punto è creare un collegamento rapido e di facile accesso a questa documentazione. Se lo metti in sharepoint e lo rendi una risorsa scaricabile che deve essere autenticata e decompressa e quindi aggiunta ai segnalibri da parte dell'individuo, puoi aspettarti di trovare la maggior parte delle persone che non si preoccuperà. Se è solo un altro segnalibro nel browser, puoi aspettarti che molte persone lo visualizzino, e visualizzarlo è il motivo per cui lo fai in primo luogo.

Personalmente, manterrei le revisioni solo per le vecchie versioni stabili. Le build sono molto transitorie, anche se dovrai mantenere una versione "corrente" o "ultima" che viene sempre sovrascritta con la build corrente. Se è generato, non ha senso archiviare anche l'output. Potresti, se archivi i binari solo in modo da non doverlo rigenerare, ma lo fai solo per le versioni finali.