Creazione di un efficace sito Web e documentazione della libreria C ++

Question

Creazione di un efficace sito Web e documentazione della libreria C ++

#1 da (3 voti)

8

Creare una libreria C ++ significa anche documentarlo in modo che altri possano usarlo e la documentazione può variare notevolmente in termini di qualità.

Come deve essere strutturato un sito Web per una libreria C ++ in modo che sia più efficace?

Direi che "il più efficace" è diviso tra tre gruppi specifici di stakeholder della biblioteca, che dovrebbero essere in grado di trovare e imparare ciò di cui hanno bisogno per partecipare e utilizzare la biblioteca:

I nuovi utenti necessitano di un'introduzione, di un download, di una configurazione e di una documentazione eccellenti e facili che passino chiaramente da un passaggio all'altro.
Gli utenti esperti hanno bisogno di una solida referenza con accesso rapido ai dettagli di cui hanno bisogno e informazioni chiare sui nuovi aggiornamenti.
I nuovi contributori hanno bisogno di un modo per guidare che copre i passi che devono compiere per ottenere i loro contributi nella biblioteca.

Mi piacerebbe capire come rendere ognuno molto felice con quello che vede e usa. Questa domanda è un po 'un incrocio tra la programmazione professionale e l'esperienza utente.

Per esempi specifici, Boost è una delle migliori raccolte di librerie, ma l'installazione iniziale, la documentazione di riferimento e capire come contribuire possono essere un po 'confuso.

D'altra parte, ho trovato cppreference.com e SGI STL documentazione per essere molto chiara e utile con spiegazioni, collegamenti ed esempi.

Sebbene gli esempi siano puramente opinioni e altri possano differire, aiuta a dare un contesto alla domanda che sto ponendo.

c++ documentation

posta Andrew Hundt 10.10.2013 - 19:49

fonte

1 risposta

Leggi altre domande sui tag c++ documentation

In quale livello deve essere localizzata la validazione? Come ridimensiono un bot / servizio?

score 3 · Accepted Answer

Nella mia precedente azienda abbiamo iniziato a generare documentazione e avere un lavoro di configurazione periodico eseguito ogni notte e pubblicarlo come una serie di pagine web a cui fare riferimento la wiki del nostro team.

Come è stato suggerito nei commenti alla tua domanda, abbiamo usato doxygen. Una cosa che mi è davvero piaciuta è stata introdotta nella versione 1.8 era la possibilità di avere una directory (o un intero albero) di documenti di markdown, mentre prima doxygen era generato esclusivamente dai file sorgente.

La struttura che avevamo era una schermata di benvenuto (markdown) che aveva collegamenti a vari luoghi. Uno di questi era un'architettura di prodotto che mostrava 30.000 piedi di vista del prodotto e evidenziava i principali servizi. Poi da quella pagina, ci sono stati Mi piace ad altre pagine di markdown che hanno ampliato ciascuno dei servizi e hanno presentato un design di altissimo livello di ciascuna (10k foot view?).

Anche dalla pagina principale, abbiamo avuto collegamenti a raccolte di guide utente che abbiamo scritto per spiegare come utilizzare un codice di utilità / framework comune.

E lentamente abbiamo iniziato a migrare i documenti di progettazione esistenti (scritti in MS Word e memorizzati nel punto di condivisione) in un formato doxygen che in realtà si è dimostrato più semplice di quanto ci si aspetterebbe. Se non fosse per i diagrammi, che dovevano essere esportati singolarmente e salvati come JPEG, un documento di progettazione di 20-30 pagine poteva essere convertito in formato doxygen markup in circa 15-30 minuti ed era così semplice che un co-op poteva farlo < sup> (*) .

La bellezza che amavo usare doxygen per questo tipo di documentazione oltre a poter generare HTML o PDF dalla stessa fonte, era che potevamo legare tutta la nostra documentazione direttamente alle pagine di riferimento di classe / funzione generate dall'intestazione di analisi File. Quindi è stata una struttura molto bella che sarebbe passata da "benvenuto" - > "architettura" - > "design" - > fino alla documentazione a livello di classe.

E siccome il tutto era in markdown, è stato molto semplice generare contenuti (molto più facile del tentativo di spiegare a un team di ingegneri come usare correttamente gli stili di MS Word) e la documentazione è stata archiviata proprio lì con il codice sorgente così come sono state introdotte nuove versioni e modificato il design / l'architettura, la documentazione sarebbe sempre stata sincronizzata con esso.

^(*) - j / k abbiamo avuto ottime cooperative (per la maggior parte) e hanno apportato molti fantastici contributi al prodotto, ma ho fatto in modo che uno di loro facesse parte della conversione dei documenti.