MS Word è male! C'è una buona alternativa? [chiuso]

https://stackoverflow.com/questions/862298

21-08-2019
|

Domanda

Come sviluppatore Io davvero non mi piace la scrittura di documentazione, ma quando devo mi piacerebbe rendere il processo il più indolore possibile.

Il problema con Word è che viene costantemente nel mio modo . Mi preoccupa di più la disposizione di circa il reale contenuto ... è per questo che mi piacerebbe per sbarazzarsi di Word.

Idealmente mi piacerebbe scrivere il mio contenuti e poi 'compilare' in un documento.

Non ho sentito parlare di LaTeX ma non ho alcuna esperienza con esso qualunque. Questo sarebbe la giusta tecnologia per il lavoro? Che Editor (Windows) dovrei usare? E 'una buona idea per iniziare con LyX ?

EDIT: Non sto chiedendo la documentazione del codice (io uso Sandcastle per questo)

Aggiornamento 2014:

Ora abbiamo passato a GFM (GitHub aromatizzato Markdown) .

E 'davvero facile da lavorare.
Scrivi codice e la documentazione nello stesso IDE!
Tutto può essere di versione!
Ottenere l'output sia come txt grezzo, html o pdf !

Soluzione

Ho trovato che i wiki possono essere buono per questo. Trova un wiki che ti piace che ti permette di fare un po ' di formattazione, ma niente di veramente pesante. Idealmente, esso dovrebbe permettere di codice del formato facilmente troppo -. Ad essere onesti, il mark-down disponibili su SO è probabilmente un buon punto di partenza

In questo modo:

Hai il rilevamento delle modifiche built-in (assumendo un wiki decente)
È possibile modificare da qualsiasi
Tutti vedono sempre la stessa documentazione (distribuzione istantanea)
È possibile concentrarsi sui contenuti invece di formattazione

Altri suggerimenti

La mia soluzione a questo è stato quello di investire un po 'di tempo nella creazione di un modello decente Word per me.

La cosa importante da fare è assicurarsi di avere uno stile definito per tutto ciò che si può mettere nel documento.

Una volta che avete tutti gli stili definiti e tutto il contenuto del documento con tag con lo stile corretto al posto di formattata in modo ad hoc, sarete sorpresi di quanto sia facile è quello di produrre una buona ricerca i documenti di Word in modo rapido ogni volta.

Il problema più ampio qui è che tutti passa ore in Word e tuttavia è molto raro per le aziende a investire nella formazione Word. Ad un certo punto si deve stringere i denti e prendere il tempo per insegnare a te stesso come usarlo correttamente, proprio come si farebbe con qualsiasi altro strumento.

Tutto ciò che si può fare con LyX si può fare con LaTeX. LaTeX è adatto a tutti i tipi di cose; è stato utilizzato per tutto, dai manuali a tenere una conferenza diapositive ai romanzi.

Credo che LaTeX è probabilmente merita di essere esaminata come opzione; se hai mai voluto "codice" per il vostro word processor, LaTeX è per voi. Al livello più semplice è possibile definire nuovi comandi per fare le cose per voi, ma c'è un sacco di potenza c'è. E gli sguardi di uscita davvero ordinata.

A mio parere, LyX è fantastico in determinate circostanze, a portata di mano in altri, e, occasionalmente, ottiene solo nel vostro senso. Penso che dovrebbe essere visto come un artefice di produttività per LaTeX. In altre parole, imparare ad usare LaTeX prima di provare LyX . Entrambi sono, naturalmente, gratuito e disponibile per Windows, anche se la curva di apprendimento è piuttosto ripida rispetto a MS Word. Per i documenti lunghi, o un sacco di documenti analoghi, LaTeX / LyX è probabilmente un investimento utile.

Si potrebbe scrivere la documentazione utilizzando il proprio formato XML e quindi trasformarlo in qualsiasi formato con XSL (ad esempio PDF tramite FOP + XSL-FO). Si veda anche la formato XML DocBook .

LaTeX è un molto strumento potente e potrebbe anche essere eccessivo qui come è stato progettato per la letteratura scientifica / matematica. Ha una (relativamente) curva di apprendimento ripida e può essere difficile da convincere a fare esattamente come si desidera se siete nuovi a esso. AMO LaTeX, ma non è davvero un generale word processor scopo.

Avete considerato OpenOffice, invece?

LaTeX è davvero un linguaggio molto potente se avete bisogno di scrivere documenti.

Forse si può provare Texmaker , un cross-platform LaTeX Editor:

Texmaker è un ambiente pulito, altamente Editor LaTeX configurabile con buona supporto chiave calda ed estesa Latex documentazione. integra Texmaker molti strumenti necessari per sviluppare documenti con LaTeX, in un solo applicazione. Ha qualche bella caratteristiche come l'evidenziazione della sintassi, inserimento di 370 simboli matematici con un solo clic, e la "struttura vista" del documento per una più facile navigazione.

Cosa succede ad usare l'HTML? In questo modo si potrebbe quindi pubblicare la documentazione se non ci sarà bisogno di molte persone di accedervi da molti luoghi.

Nonostante tutti gli sforzi e ragionevole aspettativa non credo Elaborazione di testi è stato "risolto" ancora.

La mia risposta a quello che anch'io ho personalmente trovo un'esperienza profondamente frustrante con MS Word è quello di evitare del tutto e utilizzare uno strumento di auto-documentazione come GhostDoc per generare XML quello che ho già scritto nel codice (DRY!) e trattare con il codice XML da un sito intranet XSLT basato o simili successiva.

Stai parlando di documentare il codice vero e proprio? Se è così, mi raccomando Doxygen per il codice non gestito e Sandcastle per il codice gestito. Entrambi compilare il vostro aiuto o costruire come un sito web per voi.

Entrambe le applicazioni saranno leggere i tag speciali illustrati funzioni / classi / variabili e compilare che in aiuto.

Beh non ho mai trovato niente di sbagliato con MS-Word, in primo luogo. (Cioè se si prende il tempo per sapere come utilizzare in modo efficace). OpenOffice anzi è un sorprendente e credibile alternativa gratuita - ma poi se odiate MS Word per i problemi connessi di layout, il stesso problema sta andando verifica con OpenOffice troppo.

Non ha mai fatto il href="http://www.latex-project.org/" rel="nofollow noreferrer"> lattice sistema

ho considerato un wiki, ma ho deciso di andare con una notazione Markdown modificato, per il semplice motivo, che il contenuto di un wiki non è facilmente esportato e distribuito al di fuori del wiki stesso, mentre il Markdown può essere reso in HTML.

risposta alla domanda chris' circa il mio flusso di lavoro: Scrivo la documentazione con un'applicazione Notepad-like ( TextWrangler , solo a causa della sua funzione di word-wrapping) nel formato Markdown crudo. Poi ho un piccolo sito web la documentazione localhost con la mia modificato Markdown parser (esteso per un paio di caratteristiche e funzionalità un po 'più HTML-oriented) che verifica i timestamp per i file di documentazione -. se un file è stato aggiornato, si analizza che file in HTML, e memorizza il file in una cache

In questo modo sono in grado di modificare la documentazione fonte sul mio desktop, e basta premere F5 nel browser per vedere immediatamente i risultati.

Non ho tempo di provare ancora, ma ho sempre pensato AsciiDoc sarebbe un bene per questo genere di cose.

Se volete qualcosa di più semplice di LaTeX, è possibile dare un'occhiata a ristrutturati Testo

Leggete questo libro: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer . V'è una certa idea fissa all'interno, in modo che la documentazione dovrebbe essere costruito automaticamente. Pensare di utilizzare il vostro IDE per questo, o cercare alcuni strumenti aggiuntivi. La maggior parte delle lingue moderne supportano la generazione di documentazione, come si scrive il codice. Questo può semplicemente mantenere il tuo documento in contatto con le ultime modifiche nel codice.

Io preferisco usare un editor RTF, che è molto meno clunkier delle parole. In questo modo la formattazione e tutte le intestazioni / piè di pagina sciocchezze non prenderanno la metà il vostro tempo. Wordpad ha lavorato per me in diverse occasioni. Mi sono bloccato con Word per ora, però: (

ci sono un sacco di modi possibili:

documentazione embedded, ad esempio, javadoc: buona per descrivere le API, non così buono per il "quadro"
html pianura: può essere controllato in sotto controllo di versione, un plus
un wiki, per esempio confluenza - ottimo per la collaborazione, ma ha il controllo di versione diversa dalla sorgente
LaTeX o somesuch: più adatto per i libri o documenti di documentazione tipica; il supporto per la grafica è ingombrante
un clone di Office, ad esempio, OpenOffice: in gran parte la stessa Parola + Visio, ma open source, con un formato di documento più bello

Io di solito documentare la struttura del software (le "metafore" di un progetto, interrelazioni componenti, sistemi esterni) in anticipo, utilizzando Visio, in UML "a mano libera". Questi vengono poi inserite in confluenza, che può essere convertito in PDF se qualcuno vuole una stampa.

LyX

LyX è un WYSIWYM front-end per LaTeX: È possibile ottenere la convenienza di un alimentatore di originali (in qualche modo simile a Word) con la consistenza e la potenza di LaTeX: non ottiene nel vostro senso e può fare un molto di cose che hanno bisogno di scrittori professionisti.

Nota: La risposta corretta per in realtà dipende il vostro modo di pensare --- non possiamo decidere per voi. Questa risposta dimostra semplicemente una scelta eccellente se si pensa di documentazioni come documenti e volete qualcosa di simile a Word (dove Word è buono) che non succhiare come Word (dove Word è un male per i programmatori).

Ma molti programmatori pensano di documentazione in modo diverso e, quindi, preferiscono diverse metafore. Io stesso ho avuto lo stesso problema anni fa, ha lavorato con LaTeX (come io sono un matematico), trovato LyX e finalmente risolta su un sistema / Fonte Wiki che io stesso ho scritto.

Vim è la soluzione per tutto ciò che significa scrivere testo normale nel modo più efficiente possibile. Se avete bisogno di formattazione, quindi utilizzare XML, in lattice o qualcosa di simile (in Vim).

Vim ha cambiato la mia vita!

Risposta semplice:. LaTeX suona come proprio quello che state cercando

Io lo uso per scrivere documentazione me stesso. Non potrò mai tornare a Word se ho la possibilità.

PHC , abbiamo iniziato con il lattice, per poi trasferirsi a docbook, e si sono stabiliti (in modo permanente spero) su ristrutturate Testo / Sphinx.

Il lattice è stato scelto perché siamo accademici, e lattice è lo strumento di scelta. Credo che non ha generato abbastanza buono HTML.

Docbook è stato scelto per il potere, ma era molto ingombrante. E ci hanno scoraggiato la scrittura di qualsiasi documentazione: codice doveva essere formattato manualmente, abbiamo mantenuto dimenticando la sintassi, ed era difficile da leggere. La curva di apprendimento è stato anche ripida.

Infine, ci siamo trasferiti a reST , utilizzando sfinge , e che è stata una grande decisione. La documentazione è ora molto facile da scrivere, ed entrambi PDF HTML versioni sembrano belle (anche se il PDF potrebbe fare con un po 'di personalizzazione). E 'molto facile da personalizzare troppo.

La cosa migliore in merito a Rest, però, è che la sua leggibile in forma sorgente. Questo è un vantaggio meraviglioso. Ho passato a utilizzare riposo per tutta la mia roba ora, in particolare tutto ciò attraverso il web (ad eccezione, naturalmente pubblicazioni accademiche, dove si sarebbe sciocco da usare nulla, ma in lattice).

Si consiglia di guardare in doxygen a http://www.doxygen.nl/ , vedi le loro belle esempi. In questo caso, la documentazione è presentato da tag nei commenti nell'origine.

Un'altra opzione sarebbe quella di utilizzare un sistema online come trac da http://trac.edgewall.org/ che è un / doc / sistema wiki IssueTracking che vive in cima alla sovversione.

Autorizzato sotto: CC-BY-SA insieme a attribuzione

Non affiliato a StackOverflow