Quale strumento/quadro utilizzare per la documentazione tecnica?

Question

Sviluppiamo prodotti e strutture da utilizzare con la nostra organizzazione. Sto cercando strumenti di documentazione amichevoli per i programmatori. Ho fatto qualche ricerca su alcune opzioni prima, ma non ho potuto decidere quale usare. Sto cercando suggerimenti dalle persone che hanno già utilizzato questi strumenti.

1. docbook: Spring Framework e ibernazione uso questo formato e questo sembra buono. ma credo che abbiano personalizzato il default xslt/stylesheet. Posso copiare e usare i loro xslt e css (naturalmente con i colori e le immagini cambiati). Posso integrare la generazione di documenti usando Maven?

2. wiki: questo non è amichevole per gli autori di documenti tecnici e la documentazione non sembra professionale. non è possibile anche il versioning

3. word doc: questo è quello che usiamo attualmente ma è difficile collegare e riutilizzare documenti comuni.

4. DITA?

Answer 1

DocBook

Copia fogli di stile: si, è possibile copiare e adattare i fogli di stile. I fogli di stile XSL per DocBook sono molto flessibili, ma non di facile comprensione. Dovrai impiegare alcuni giorni per farli funzionare come ti piace.

Integrazione Maven: sì, ci sono plugin Maven in cui è possibile integrare la generazione di documenti (ad esempio PDF, HTML ecc.) Nel processo di compilazione. Lo stiamo facendo, inclusa la filigrana solo per SNAPSHOTS e la distribuzione su archiva al momento del rilascio.

Answer 2

Non sono sicuro se siete alla ricerca di ulteriori suggerimenti o semplicemente un feedback su quelli che avete elencato/hanno ristretto la scelta, ma ...

Python utilizza una combinazione di reStructuredText e Sphinx, che è una toolchain che ho iniziato ad adottare sul lavoro e mi sto divertendo.

Di quelli che hai elencato, ho già usato i wiki ed è stato spiacevole per molti motivi, alcuni dei quali sono stati toccati. Anche la parola sembra una scelta sbagliata; tra quelli sceglierei docbook ma so molto poco su di esso, in modo da ...

Answer 3

Sono abbastanza soddisfatto anche se DocBook la rampa-up iniziale (tra cui la regolazione dei fogli di stile) non è così facile. Ma una volta che tutto è fatto, è davvero facile da usare.

corro la mia generazione docbook da un build.xml Ant attraverso il compito XSLT standard. Se Maven ti consente di chiamare un processore XSLT, tutto dovrebbe andare bene.

L'unico inconveniente (che ho trovato) è il modo in cui libri di grandi dimensioni devono essere gestite (per evitare di avere tutto in un unico file XML enorme)

Ogni capitolo è un file XML separato che non è purtroppo una completa file di DocBook come viene incluso usando attraverso entità di sistema:

 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 
[ 
    <!ENTITY chapter_1 SYSTEM "chapter_1.xml"> 
    <!ENTITY chapter_1 SYSTEM "chapter_1.xml"> 
]> 

<?xml-stylesheet href="html.css" type="text/css"?> 

<article lang="en"> 
    <title>The Manual</title> 

    &chapter_1; 
    &chapter_2; 

</article> 

Poi chapter_1.xml assomiglia a questo:

 
<section id="chapter_1"> 
.... 
</> 

ci potrebbe essere scommessa Le soluzioni ter là fuori, ma non li ho trovati;)

Answer 4

La stessa domanda è anche arised nel nostro progetto. Fino a quel momento, usavamo semplici documenti HTML e word, ma queste soluzioni non erano soddisfacenti.

Ora usiamo DITA e lo consiglio davvero. È più leggero di DocBook e si applica molto bene alla documentazione del software.

Alcuni professionisti:

• DITA consente la separazione di contenuto e di styling
• La separazione del contenuto e stile permette di generare la documentazione per vari formati, ad esempio HTML o PDF. Ad esempio, utilizziamo DITA per generare EclipseHelp della nostra applicazione basata su RCP Eclipse.
• DITA definisce uno spazio dei nomi specifici software (per esempio <input> o <menu-item> e simili)
• DITA viene fornito con script di build per i vari formati di output, che possono essere facilmente adattati alle vostre specifiche esigenze.

Vedi anche DITA Open Toolkit Project Home

Answer 5

Usare un Wiki.

vostre obiezioni:

questo non è amichevole per gli scrittori di documenti tecnici e la documentazione non sembra professionale. Non è possibile anche il controllo delle versioni

Ci sono wiki che consentono la modifica WYSIWYG. La documentazione tecnica per un progetto interno alla casa non ha bisogno di "sembrare professionale". Il controllo delle versioni globali è un problema, ma non lo considero altrettanto importante.

D'altra parte, il grande vantaggio di un wiki è uno che non può essere valutato abbastanza bene, soprattutto per un prodotto interno: facile contributo e collaborazione. Ogni utente del prodotto può contribuire alla documentazione e se è possibile stabilire una cultura della collaborazione sulla documentazione, il risultato sarà (letteralmente) dieci volte più utile della media "Pulsante X fa A, pulsante Y fa B" tecnico documenti prodotti da scrittori che non stanno effettivamente utilizzando il prodotto. Nessuno ha bisogno di quelli Le persone hanno bisogno di guide "Howto", Glossari, FAQ e soluzioni alternative.

I wiki consentono e favoriscono questo tipo di collaborazione utile. Gli strumenti di authoring "professionali" con restrizioni di accesso e processi di approvazione lo uccidono.

Answer 6

È inoltre possibile combinare approcci:

• Usa Wiki per l'authoring di avere come sempre più persone coinvolte in quanto solo gli scrittori tech. In questo modo, ad es. gli sviluppatori o lo staff di supporto possono partecipare facilmente.
• Esistono strumenti che convertono almeno dal Wiki al DocBook, come ad esempio il Wiki di DocBook o l'esportatore di Wiki di scorrimento della mia azienda (http: // k15t.it /) che esporta dal wiki di Confluence a DocBook e integra i fogli di stile di DocBook per la personalizzazione estesa (commentario dei commenti dei macker sopra) incl. RenderX XEP.

Spero che questo aiuti,

-Stefan