Qual è un buon strumento per scrivere un manuale utente (file di aiuto), che si integra con il controllo versione [chiuso]

Question

Le persone che scrivono il manuale dell'utente non sono necessariamente programmatori e hanno bisogno di un editor visivo. Un problema importante è il formato interno dello strumento di creazione; dovrebbe essere leggibile text / html, quindi è facile confrontare le versioni delle singole pagine controllate nel controllo delle versioni.

Answer 1

Esistono altri prodotti professionali che consentono di scrivere file di aiuto e hanno il supporto di "ID contesto" " che rende possibile un aiuto sensibile al contesto. Doc To Help e RoboHelp sono questi tipi di prodotti.

Answer 2

DocBook

_{(fonte: docbook.org )}

Answer 3

Microsoft HTML Help Workshop può essere utilizzato per creare file di aiuto CHM professionali di buona qualità. Tutto ciò che serve è un mucchio di file HTML. Lo strumento "compila" tutti questi e raggruppati in un unico file della Guida. I file HTML possono essere generati utilizzando Microsoft Word / Frontpage o anche Dreamweaver. Potresti prendere in considerazione la fonte che controlla questi file HTML.

Answer 4

Latex . Lyx fornisce WYSIWYM per la scrittura di file in lattice.

Answer 5

Nel mio vecchio lavoro hanno usato uno strumento del software madcap chiamato flare .

Sembrava funzionare davvero bene.

Answer 6

Una buona combinazione da considerare è Subversion, DocBook e Publican.

• Controllo versione = Subversion
• Authoring dei contenuti = DocBook
• Publishing = Publican
• WYSIWYG facoltativo = Serna

Al momento, questa è una delle toolchain in uso dal più grande fornitore al mondo di soluzioni open source e il nome dietro gran parte dell'uso mondiale di sistemi operativi basati su Linux nel mercato aziendale. La maggior parte (e vicino a tutti) della documentazione ufficiale di Red Hat è stata creata in questo modo. Lo stesso vale per Fedora.

Il principale "pro" ecco che si tratta di strumenti liberamente disponibili, con una forte sovrapposizione nel mercato degli scrittori tecnici. Tutto ciò sarà in grado di (ma non vorrebbe) scrivere in XML e raccogliere DocBook è come raccogliere HTML negli anni '90. Subversion è uno strumento di controllo della versione molto comune, che come DocBook è relativamente facile da implementare e utilizzare. Publican è un ottimo strumento di pubblicazione che può prendere DocBook XML e pubblicarlo su PDF, HTML, HTML-single, ecc. Ovviamente i tuoi scrittori possono usare un WYSIWYG come Serna, ma io uso frammenti in Geany (su Fedora) o TextMate (su OS X) personalmente.

Il principale "con" è la percezione del tecnicismo. I tuoi scrittori potrebbero volere WYSIWYG (e possono averlo) e, a seconda delle tue esigenze di documentazione, questo potrebbe essere quello che stai usando. Come saprai, esiste un mercato là fuori per " Scrittori tecnici " specializzato nella correzione degli stili (e del markup) di Microsoft Word, quindi gli argomenti per la separazione di "authoring" da " publishing " si basano su casi d'uso comprovati ma distinti per le organizzazioni che richiedono che la documentazione sia mantenuta agli stessi standard di ingegneria / programmazione / produzione di origine.

Alcuni dei consigli estremi che riceverai provengono da persone e aziende che sono state esposte al valore della documentazione XML, e in particolare quelle nei regni di DITA, in cui alcuni multinazionali hanno una reputazione per acquisizioni che sono influenzate da il formato e la disponibilità della conoscenza del prodotto. ci sono anche argomenti che bloccano la tua documentazione in un "appiccicoso" o il formato chiuso non aiuta i futuri requisiti di manutenzione. È qui che le opzioni open source ottengono supporto a livello aziendale. Inoltre, ovviamente, è gratuito.

Answer 7

Puoi usare Subversion e MGTEK Help Producer. Help Producer crea file di aiuto da documenti Word. TortoiseSVN viene fornito con script per confrontare diverse revisioni dei documenti di Word, in Word stesso (Word ha uno strumento di confronto delle versioni).

I tuoi utenti vorranno uno strumento di differenza visiva che assomigli a quello in cui stanno modificando. Se non sono solo tecnici, DocBook o Latex non funzioneranno (ho provato a dare entrambi i miei utenti, e ho anche provato Epic Editor come editor di DocBook che è molto costoso ma non ha funzionato molto bene dopo tutto). Attenersi a qualcosa che sanno (Word) ti eviterà molti mal di testa.

All'inizio ero molto riluttante a seguire questa strada, perché volevo una soluzione più "tecnicamente perfetta", ma nel tempo mi sono reso conto che avere utenti felici e produttivi era più importante. Dico solo che so da dove vieni, ma prova il percorso di Word: in pratica funziona molto meglio di tutte le soluzioni "pure" basate sul testo che sono là fuori. Agli utenti regolari non piace la modifica basata sul markup.

Answer 8

Se stai usando Visual Studio, dai un'occhiata a SandCastle - http://www.codeplex.com / Sandcastle .

Esistono anche un paio di strumenti che ti aiutano a creare file sandcastle, prova a cercare " sandcastle " su codeplex. Uno di questi è SandCastle Help File Builder ( http://www.codeplex.com/SHFB ), ma non l'ho mai usato, quindi non so se gli utenti non tecnici ne saranno soddisfatti.

Answer 9

Madcap Flare è il miglior strumento commerciale in circolazione. Scritto dagli ex sviluppatori di Robodoc

Answer 10

Ho creato un sistema di documentazione chiamato Mandown ( Markdown / Html / Javascript / basato su file documenti relativamente collegati per la portabilità) che andrebbero facilmente sotto il controllo della versione. La parte dell'editor visivo che dovresti capire separatamente - A volte uso HTML-Kit che almeno ha una funzione di anteprima.

Vedi Qual è il modo migliore per archiviare software documentazione?

---

Ecco un altro strumento da verificare: Xilize

Answer 11

Stiamo utilizzando APT . Si integra bene con l'elemento della configurazione (artefatto di build standard) ed è più attivo rispetto ad esempio al documento word. È anche possibile generare PDF e altri formati quando necessario.