Quali strumenti utilizza il tuo team per scrivere manuali utente? [chiuso]

StackOverflow https://stackoverflow.com/questions/314117

Domanda

Le richieste di base sono:

  • formato leggibile / di testo (per un facile controllo della versione)
  • online (per collaborazione)
  • formattazione semplice (markdown ok, html è troppo)
  • formattazione rigorosa (quindi gli autori non inventano nuovi tipi di titoli, proiettili ecc.)
  • esportabile in PDF, HTML
  • backup e distribuzione semplici (in modo che possiamo "implementare" sul sito dei clienti come versione sola lettura)

Stiamo pensando di utilizzare un qualche tipo di motore wiki, ma dovrebbe utilizzare i file per l'archiviazione o disporre di altri mezzi di "distribuzione". al cliente ed essere facile da installare / manutenere. Inoltre, dovrebbe essere gratuito / economico (la confluenza è troppo costosa)

Qualche suggerimento?

Modifica: non sto cercando strumenti per documentare il codice, ne abbiamo parlato con Sandcastle.

È stato utile?

Soluzione

Anche se potrebbe non rispondere a tutte le tue richieste, DokuWiki potrebbe valere la pena dare un'occhiata.

Come con altri wiki, ha una sintassi semplice e ha il controllo della versione su monitora le revisioni , genera sommario e una ricerca full-text che può tornare utile per un sistema di aiuto .

Potresti voler valutare elenco delle caratteristiche per vedere se soddisferà le tue esigenze.

Inoltre, sembra esserci anche una buona raccolta di plugin disponibili . Anche se non ho usato DokuWiki o i suoi plugin, sembrano esserci plugin disponibili per esportazione PDF pure.

Altri suggerimenti

Per la nostra API, utilizziamo Doxygen , il che è fantastico.

Pandoc è uno strumento fantastico per la conversione tra vari formati di markup. Scriviamo documenti in markdown e usiamo Pandoc per convertire in altri formati.

Dal sito pandoc:

  

Se è necessario convertire i file da uno   formato markup in un altro, pandoc è   il tuo coltellino svizzero. Pandoc può leggere markdown e   (sottoinsiemi di) reStructuredText,   tessile, HTML e LaTeX, e può farlo   scrivere testo semplice, markdown,   reStructuredText, HTML, LaTeX,   ConTeXt, PDF, RTF, DocBook XML,   OpenDocument XML, ODT, GNU Texinfo,   Markup MediaWiki, tessile, uomo groff   pagine, modalità org di Emacs, ebook EPUB,   e slide show HTML S5 e Slidy. PDF   è supportato anche l'output (tramite LaTeX)   con il wrapper markdown2pdf incluso   script.

Pandoc ottiene punti extra per essere open source e scritto nel calore che è Haskell;)

Non posso dire abbastanza cose positive di Asciidoc . Ha una sintassi di markup molto semplice, può generare qualsiasi cosa, da pdf a roff, portatile da implementare e molto facilmente inserito in qualsiasi wiki con solo alcune piccole modifiche.

Anche nel suo stato di markup, è molto, molto facile da leggere. L'unica cosa che devo giocherellare quando lo uso sono i tavoli, ma non è troppo difficile.

Se conservi i file in formato testo nel tuo repository, il monitoraggio delle revisioni è abbastanza semplice.

Per la documentazione del codice, utilizzo doxygen .

Utilizziamo aiuto e manuale per il manuale e il file di aiuto. Non è prevista l'esportazione in html, ma fornisce aiuto in html, winhelp, pdf e altri formati.

Stiamo usando un wiki. Consiglio MoinMoin perché

  • molto semplice da installare (anche su un laptop)
  • molto semplice da eseguire il backup (puoi persino eseguire il commit del wiki in un sistema di controllo versione per sincronizzarlo, per esempio, con i laptop per l'utilizzo offline).
  • bella sintassi
  • facile da estendere
  • Facile da cercare

Non stiamo usando qualcosa come Word perché:

  • La documentazione è troppo veloce
  • La ricerca di tutti i documenti è una seccatura
  • Il collegamento tra bit di informazioni è una seccatura
  • Nessuna differenza tra le versioni
  • Formato binario che fa schifo da qualsiasi VCS
  • Nessun segnalibro profondo
  • I documenti diventano troppo grandi e poi diventano goffi: divisi (e non c'è più ricerca) o attendono anni per caricarsi.

Non menzioni la lingua / il framework che stai utilizzando. Esistono davvero ottimi strumenti di documentazione, ma alcuni sono specifici per quello in cui stai sviluppando. Siamo un negozio C #, quindi la mia risposta si applicherà solo a te se stai usando .NET.

Utilizziamo Sandcastle , che non è solo gratuito, ma open source. Mentre le persone lo considerano principalmente come un'applicazione rigorosamente che genera documentazione dalla documentazione XML, è possibile fornire il proprio contenuto in MAML. Può rivolgersi sia a CHM che a distribuzioni di siti Web, il che soddisfa le nostre esigenze. Ci sono alcuni strumenti aggiuntivi che possono fornire elementi come la marcatura dei preferiti e la valutazione degli argomenti per la mia comprensione, ma non abbiamo ancora iniziato a usarli ancora.

Questo ci fornisce documentazione interna ed esterna. Dal momento che utilizziamo anche Team Foundation Server, utilizziamo il Wiki integrato sul progetto team in Sharepoint, ma è più orientato alla collaborazione del progetto.

Modifica: risolto il collegamento interrotto e volevo anche menzionare che ci sono altri strumenti insieme a Sandcastle, che usiamo. Cose come Sandcastle Help File Builder e GhostDoc sono strumenti comuni. Il primo a modificare i progetti Sandcastle e MAML e il secondo a migliorare la qualità dei commenti nel codice.

Prova Sphinx . Tutta la documentazione di Python è realizzata utilizzando questo strumento http://docs.python.org/

Per " manuali " ;, Docbook. È un dialetto SGML progettato per la documentazione tecnica. http://www.docbook.org/ . Potrebbe non soddisfare il tuo "facile markup" criterio ma produce sicuramente un buon output in LaTex (può essere convertito quindi in PDF) e un buon output HTML se si cucina il proprio foglio di stile CSS per questo. File di testo mantenuti nel controllo versione. Tutti i programmi usano anche una libreria che combina l'analisi della riga di comando con l'analisi di " - help " output in una scelta di formati (normale, pagina man e docbook). Per il riferimento API, ovviamente doxygen.

Nel mio lavoro attuale sforniamo software monouso, quindi la documentazione viene spesso messa in disparte e viene eseguita in Word.

Nel mio ultimo lavoro, tuttavia, il team di documentazione sembrava costantemente infuriarsi su prodotto del software mad cap " Flare " . Ti consente di scrivere in un formato e pubblicare su molti supporti in modo che il tuo manuale possa essere anche la tua guida online o un sito Web, ecc ...

Usiamo Word. Viene messo nel nostro controllo di versione, quindi abbiamo una cronologia (c'è una cartella della documentazione collegata ad ogni progetto). La formattazione può essere controllata utilizzando modelli, tutti ora configurati, quindi è facile apportare modifiche all'interno degli standard di layout. I file possono essere esportati in PDF. Puoi pubblicarli come documenti di sola lettura da condividere con gli utenti.

Abbiamo avuto un grande successo con DocToHelp . Funziona benissimo con la documentazione basata su Microsoft Word e altri moduli e ha anche alcune fantastiche funzionalità di integrazione per Visual Studio.

La parte migliore è una volta importata una base di documenti di base in DocToHelp, puoi scegliere uno dei numerosi formati di esportazione sia WinHelp, HTML Help, Java Help o il simpatico ed elegante Net Help ricercabile.

Per documentare il codice che uso Doxygen. Preferisco la versione di Linux, ho avuto problemi con alcune funzionalità nella versione di Windows

La mia azienda utilizza MediaWiki e TikiWiki per la maggior parte della documentazione. Abbiamo anche un ragazzo che compila materiale in formato MS Word e PDF per la stampa / invio ai clienti. Ti consiglierei di evitare TikiWiki come la peste. MediaWiki è fantastico, sia perché è davvero facile da usare sia perché tutti sanno come usarlo - è il wiki standard di fatto, e meritatamente, IMHO.

Da qualche tempo usavamo DocBook, ma è stato molto difficile estenderlo con funzionalità più avanzate e necessarie (evidenziazione della sintassi, suddivisione in più file, gestione della multilinguità ecc.). Successivamente, abbiamo deciso di scrivere da zero il nostro sistema e di rilasciarlo come open-source: link text . Utilizza file di testo semplice e Markdown come linguaggio di sintassi e ora abbiamo tutto ciò di cui abbiamo bisogno. Lo svantaggio è che attualmente non esiste probabilmente alcun parser Markdown che produca qualcosa di diverso dall'output HTML. Per ora questo è abbastanza, ma stiamo pensando di implementare il supporto PDF molto presto.

Inoltre, stiamo mantenendo MediaWiki come un aiuto basato sulla comunità.

Autorizzato sotto: CC-BY-SA insieme a attribuzione
Non affiliato a StackOverflow
scroll top