Hai bisogno di consigli - Lo sviluppo di un sistema di documentazione flessibile, fortemente incentrata sulla localizzazione [chiusa]

Question

mi è stato accusato di costruzione di un sistema di documentazione / piattaforma.

Ecco un breve elenco dei principali requisiti:

• facilmente localizzato: Questo dovrà sostenere una dozzina di lingue fuori dal cancello. (La possibilità per il personale non tecnico per aggiungere / traduzioni aggiornamento sarebbe un grande vantaggio, anche se non al 100% richiesto)

• La flessibilità in formati di output: Al minimo indispensabile, ho bisogno di emettere i documenti (sia nel loro insieme o in blocchi selezionati) come PDF e HTML. I punti di bonus per i formati nativi di Windows, come file della Guida.

• Gestito e distribuito tramite un'interfaccia utente intuitiva (web, idealmente).

Mi chiedo se voi gente sa di eventuali sistemi di là fuori che supportano questo tipo di cose già? Io non sono contrario a scrivere questo da zero, ma preferisco non reinventare la ruota se posso farne a meno.

I due principali candidati che ho incontrato finora sono DocBook e reST . Il primo sembra aver ottenuto una reputazione per, beh, succhiare. Sono familiarità con entrambi, ma mi hanno detto che il riposo mi avrebbe ottenere una buona porzione della strada.

Altri suggerimenti? Sarei meglio costruire questo da zero?

Answer 1

posso consigliare DocBook se avete bisogno di creare documentazione tecnica tradizionale: libri, divisi in capitoli, divisi in sezioni, ecc penso che ci sono tre cose principali da considerare: il markup in sé, la modifica toolchain, e la toolchain pubblicazione .

Markup. Il markup XML DocBook è molto completo, che contiene il supporto per quasi ogni aspetto immaginabile quello che potrebbe essere incluso in un volume techical e poi alcuni. Ciò include il materiale di base per libri come riferimenti incrociati, note, ecc, nonché di marcatura specifico per la documentazione del software, come elenchi di programmi, di riferimento voci ecc Il riferimento essenziale per il markup è DocBook: The Definitive Guide da Norman Walsh e Leonard Muellner

.

La lingua del contenuto può essere esplicitamente marcato utilizzando attributi lang, in modo che il documento di origine può contenere il contenuto in più lingue, e la versione nella lingua desiderata può essere estratto in fase di elaborazione.

Strumenti di authoring. A causa della vastità del vocabolario DocBook, una sorta di editor di "schema-aware" è praticamente un requisito. Un buon editor vi aiuterà con la scelta degli elementi di markup e farà in modo di produrre codice valido. Un editor XML decente farà, ma a seconda di come tecnico vostri autori di documentazione sono, si potrebbe anche prendere in considerazione qualcosa di più user-friendly. Ci sono alcuni editor in stile WYSIWYG disponibili. (Ho usato XMLMind XML Editor , ed ero abbastanza soddisfatto.)

strumenti Publishing. Il metodo standard di fatto di generare in uscita dal markup DocBook XML è DocBook XSL distribuzione di stile. Ha il supporto per i formati di output multple, tra cui HTML, XSL-FO (per l'output PDF), HTML Help, anche le pagine man. L'output generato dal foglio di stile può essere controllato da molti parametri, e la prima cosa da consultare quando si vuole regolare l'uscita è il documentazione di riferimento distribuiti con i fogli di stile.

Se e quando si desidera un maggiore controllo sul l'output prodotto, tuttavia, è necessario personalizzare i fogli di stile XSLT per l'uso specifico. Questo potrebbe sembrare un po 'scoraggiante, soprattutto se non si dispone di una precedente esperienza di XSLT. Tuttavia, c'è un libro eccellente libero disponibile sul tema: DocBook XSL: The Complete Guide da Bob Stayton.

Per la conversione XSL-FO in PDF, avrete anche bisogno di un processore XSL-FO. C'è il libero e open source Apahce FOP e poi ci sono diverse opzioni commerciali.

Molto probabilmente, il vostro processo di pubblicazione probabilmente finirà per sembrare un sistema di compilazione per la documentazione. Avrete un sistema automatizzato (probabilmente guidata da un tool di creazione, come effettuare o Ant) che avrà la vostra fonte di documentazione in formato XML e trasformarlo in formati di output desiderate nelle lingue desiderate.

---

In sintesi, direi che DocBook è una buona scelta se si sta cercando di produrre a libro, la documentazione tecnica dettagliata lineari. I principali svantaggi sono la complessità della marcatura, che può presentare una curva di apprendimento notevole per gli autori, e che possono rendere utensili speciali authoring necessario. Inoltre, la personalizzazione l'uscita dai fogli di stile DocBook XSL può ottenere abbastanza coinvolto.

Se stai cercando di produrre meno "a libro" e più "online come" Documentazione - Temi Documentazione interconnessi gli uni agli altri - si potrebbe desiderare di avere uno sguardoa DITA per un'altra alternativa basata su XML. Non ho usato, ma è anche dotato di una toolchain per la produzione di vari formati di output dal markup XML.

Answer 2

DocBook e ReStructuredText sono sicuramente i due maggiori concorrenti, ma AsciiDoc è un altro, simile linguaggio di markup che è leggibile indipendentemente dalla marcatura. Sono più familiarità con (e quindi una più grande sostenitore di) ReStructuredText, personalmente, ma AsciiDoc è solo un'altra opzione là fuori.

Dato quello che hai descritto finora, suona come MoinMoin sarebbe una buona misura sulla base del fatto che esso ha un ReStructuredText parser e è in grado di esportare le pagine in PDF . Si dovrebbe essere in grado di estrarre la fonte e gestito attraverso qualsiasi altri strumenti stand-alone, se necessario (ma potrebbe essere necessario pre-elaborare loro di eliminare qualsiasi MoinMoin-specifica markup).

Google ha un paio di altri risultati per ReStructuredText wiki se MoinMoin isn' t esattamente quello che ti serve.