Utilizzando MAML per la documentazione concettuale di libreria [chiusa]

Question

Sto lavorando ad una nuova biblioteca e sto usando i commenti XML per la documentazione API insieme a SandCastle che funziona davvero bene.

Ma ho bisogno di scrivere documentazione aggiuntiva che copre concetti, architettura generale, dimostrazioni di lavoro, ecc, diagrammi di classe, ecc.

Ho 2 opzioni:

1. Utilizzare alcuni motore wiki e scrivere la documentazione stile wiki.
2. Usa MAML che sembra essere per questo scopo.

Utilizzando wiki sembra soluzione sicura, perché ci sono molti motori stabili, popolari e libero disponibili, ma API e la documentazione concettuale non andrà di pari passo (cross-linking, aspetto, ecc). Utilizzando MAML significa una curva di apprendimento e non sono sicuro di come maturo è e quali sono i suoi vantaggi / svantaggi.

Hai usato MAML / Wiki per questo scopo e quali sono stati i tuoi insegnamenti? Cosa mi suggerisce?

Answer 1

Personalmente, amo la libertà di lavorare w / un Wiki. A questo punto, si dispone di alcune scelte decenti per l'editing MAML

• DocProject
• Sandcastle Builder Aiuto File

Non posso parlare molto di DocProject (anche se sembra bello). In questo momento, sto usando SHFB di fondere documentazione delle API e alcuni documenti concettuali in MAML. L'editor è decente e più che è sufficiente per le mie esigenze. Sono in grado di impostare facilmente una tabella di contenuti e link tra il mio API e dei documenti concettuali. Una buona risorsa per guardare gli esempi è SandcastleStyles .

Come tutte le cose, ci sono alcune importanti domande da porre.

• Avete i requisiti per spedire la documentazione in un unico pacchetto? Nel mio caso, avevo bisogno di spedire tutto in un bel pacchetto compilato. Non si può fare che w / un Wiki, ma si può fare che w / Sandcastle.
• Hai intenzione di essere l'unica persona l'aggiornamento del contenuto concettuale? La maggior parte dei wiki sono davvero un bel editore e la capacità di collegare rapidamente tra gli argomenti. L'unico strumento necessario per modificare il contenuto è un browser, che potrebbe essere un requisito per uno scrittore meno tecnicamente-savvy.