¡MS Word es malo! ¿Hay una buena alternativa?

Question

Como desarrollador, realmente no me gusta escribir documentación, pero cuando tengo que hacerlo, me gustaría hacer el proceso lo menos doloroso posible.

El problema con Word es que constantemente se interpone en mi camino. Me preocupa más el diseño que el contenido real ... es por eso que me gustaría deshacerme de Word.

Idealmente me gustaría escribir mi contenido y luego 'compilarlo' en un documento.

He oído hablar de LaTeX pero no tengo ninguna experiencia con eso en absoluto. ¿Esta sería la tecnología adecuada para el trabajo? ¿Qué editor (Windows) debería usar? ¿Es una buena idea comenzar con LyX?

EDITAR: No estoy preguntando sobre la documentación del código (uso Sandcastle para eso).

---

Actualización 2014:

Ahora hemos cambiado a GFM (GitHub Flavored Markdown).

• Es realmente fácil de trabajar.
• ¡Escriba la documentación del código & en el mismo IDE!
• ¡Todo puede ser versionado!
• Obtenga una gran salida ya sea como raw txt, html o pdf!

Answer 1

He descubierto que los wikis pueden ser buenos para esto. Encuentre un wiki que le guste que le permita hacer un bit de formateo, pero nada realmente pesado. Idealmente, también debería permitirle formatear el código fácilmente. Para ser honesto, el descuento disponible en SO es probablemente un buen comienzo.

De esa manera:

• Usted tiene el control de cambios integrado (suponiendo un wiki decente)
• Puede editar desde cualquier lugar
• Todo el mundo ve siempre la misma documentación (distribución instantánea)
• Puede concentrarse en el contenido en lugar de formatear

Answer 2

¿Qué hay de usar HTML? De esta forma, podría publicar la documentación si es necesario que muchas personas accedan desde muchos lugares.

Answer 3

Puede escribir su documentación con su propio formato XML y luego transformarla a cualquier formato con XSL (por ejemplo, PDF a través de FOP + XSL-FO). Vea también el formato XML DocBook.

Answer 4

LaTeX es extremadamente herramienta poderosa y bien podría ser exagerado aquí, ya que está diseñado para la literatura científica/matemática. Tiene una curva de aprendizaje (relativamente) empinada y puede ser complicado convencerlo para que haga exactamente lo que usted desea si es nuevo en ella. ME ENCANTA LaTeX, pero en realidad no es un procesador de textos de propósito general.

¿Ha considerado OpenOffice en su lugar?

Answer 5

Lea este libro: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer. Hay alguna idea fija en el interior, por lo que la documentación debe ser construida automáticamente. Piensa en usar tu IDE para esto, o busca algunas herramientas adicionales. La mayoría de los lenguajes modernos admiten la generación de documentación a medida que escribe el código. Esto simplemente puede mantener su documento en contacto con los últimos cambios en el código.

Answer 6

A pesar de todos los esfuerzos y las expectativas razonables, no creo que el procesamiento de textos haya sido "resuelto" todavía.

Mi respuesta a lo que me parece también personalmente una experiencia muy frustrante con MS Word es evitarlo por completo y usar una herramienta de auto-documentado como GhostDoc a generar XML de lo que ya he escrito en el código (¡DRY!) Y trate el XML desde un sitio de intranet basado en XSLT o similar más adelante.

Answer 7

Mi solución a esto fue invertir algo de tiempo en la creación de una plantilla de Word decente para mí.

Lo importante es asegurarse de tener un estilo definido para todo lo que pueda incluir en el documento.

Una vez que tenga todos los estilos definidos y todo el contenido del documento etiquetado con el estilo correcto en lugar de formatear ad hoc, se sorprenderá de lo fácil que es producir rápidamente documentos de Word atractivos hora.

El problema más amplio aquí es que todo el mundo pasa horas en Word y, sin embargo, es muy raro que las empresas inviertan en formación de Word. En algún momento debes morder la bala y tomarte el tiempo para enseñarte cómo usarla correctamente, como lo harías con cualquier otra herramienta.

Answer 8

¿Estás hablando de documentar tu código real? Si es así, recomiendo Doxygen para el código no administrado y Sandcastle para el código administrado. Ambos recopilarán su ayuda o la compilarán como un sitio web para usted.

Ambas aplicaciones leerán etiquetas especiales encima de funciones/clases/variables y las compilará en la ayuda.

Answer 9

Es posible que desee buscar en doxygen en http://www.stack.nl/~dimitri/doxygen/, consulte sus buenos ejemplos. En este caso, la documentación se presenta mediante etiquetas en comentarios en la fuente.

Otra opción sería utilizar un sistema en línea como trac desde http://trac.edgewall.org/ que es un sistema wiki/doc/issuetracking que se basa en la subversión.

Answer 10

Prefiero usar un editor RTF que es mucho menos ruidoso que las palabras. De esta forma, el formateo y todas las tonterías de encabezados/pies de página no ocuparán la mitad de tu tiempo. Wordpad me ha funcionado en varias ocasiones. Estoy atascado con Word para ahora, sin embargo :(

Answer 11

hay una gran cantidad de formas posibles:

• documentación incorporado, por ejemplo javadoc: buena para la descripción de las API, no tan bueno para el "cuadro grande"
• html simple: se puede verificar en el control de versiones, una definición definitiva más
• wiki, por ejemploConfluence: ideal para la colaboración, pero tiene un control de versiones diferente de su fuente
• LaTeX o somesuch: más adecuado para libros o documentos que la documentación típica; la compatibilidad con gráficos es engorrosa
• una copia de Office, p. OpenOffice: mayoría los mismos que la Palabra + Visio, pero de código abierto, con un formato de documento más agradable

lo general documentar la estructura del software (las "metáforas" de un proyecto, las interrelaciones de los componentes, sistemas externos) en la delantera, usando Visio, en UML "freeform". Estos se incrustan en la confluencia, que se puede convertir a PDF si alguien quiere una copia impresa.

Answer 12

Todo lo que puede hacer con LyX lo puede hacer con LaTeX. LaTeX es adecuado para todo tipo de cosas; se ha utilizado para todo, desde manuales hasta conferencias y novelas.

Creo que vale la pena considerar LaTeX como una opción; Si alguna vez ha querido "codificar" su procesador de textos, LaTeX es para usted. En el nivel más simple, puede definir nuevos comandos para hacer las cosas por usted, pero hay mucho poder allí. Y el resultado parece realmente limpio.

En mi opinión, LyX es fantástico en ciertas circunstancias, práctico en otros y ocasionalmente se interpone en tu camino. Creo que debería verse como un refuerzo de productividad para LaTeX. En otras palabras, aprende a utilizar LaTeX antes de probar LyX. Ambos son, por supuesto, gratuitos y están disponibles para Windows, aunque la curva de aprendizaje es bastante pronunciada en comparación con MS Word. Para documentos largos, o muchos documentos similares, LaTeX/LyX es probablemente una inversión que vale la pena.

Answer 13

Consideré una wiki, pero decidí ir con una notación Markdown modificada, por la sencilla razón de que el contenido de una wiki no se exporta y distribuye fácilmente fuera de la misma wiki, mientras que Markdown se puede representar en HTML .

respuesta a Chris' pregunta acerca de mi flujo de trabajo: escribo la documentación con una aplicación Bloc de notas-como (TextWrangler, sólo debido a su característica de palabra-envoltura) en su formato Markdown prima. Luego tengo un small localhost documentation website con my modified Markdown parser (ampliado para algunas funciones y un poco más de funcionalidad orientada a HTML) que busca las marcas de tiempo para los archivos de documentación: si un archivo se ha actualizado, lo analiza en HTML y almacena el archivo en un caché

De esta manera puedo editar la documentación fuente en mi escritorio, y simplemente presiono F5 en mi navegador para ver los resultados inmediatamente.

Answer 14

Bueno, nunca he encontrado nada malo con MS-Word en primer lugar. (es decir, si se toma el tiempo para saber cómo usarlo de manera efectiva). OpenOffice de hecho es una asombrosa alternativa libre creíble & - pero si odias MS Word por problemas relacionados con el diseño, el mismo problema va a ocurrir con OpenOffice también.

Nunca probé el sistema Latex, pero he oído que es bueno para el trabajo científico. Creo que usar algún editor HTML WYSIWYG sería lo mejor para ti, si solo quieres enfocarte en el contenido.

Answer 15

LyX

LyX es un front-end WYSIWYM a LaTeX: Usted consigue la comodidad de un procesador de documentos (algo similar a Word) con la consistencia y el poder de LaTeX: No puede ser en su camino y puede hacer un lote de cosas que los escritores profesionales necesitan.

Nota: La respuesta correcta para que realmente depende de su forma de pensar --- que no puede decidir por usted. Esta respuesta simplemente muestra una excelente opción si piensa en documentaciones como documentos y quiere algo similar a Word (donde Word es bueno) que no apesta como Word (donde Word es malo para los programadores).

Pero muchos programadores piensan en la documentación de manera diferente y, por lo tanto, prefieren diferentes metáforas. Yo mismo tuve el mismo problema hace años, trabajé con LaTeX (ya que soy matemático), encontré LyX y finalmente me decidí por un sistema Wiki/Fuente que yo misma escribí.

Answer 16

Vim es la solución para todo lo que signifique escribir texto sin formato de la forma más eficiente posible. Si necesita formatear, utilice XML, Latex o algo similar (en Vim).

¡Vim cambió mi vida!

Answer 17

LaTeX es realmente un lenguaje muy potente si necesita escribir documentos.

Tal vez usted puede intentar texmaker, una multiplataforma LaTeX editor:

Texmaker es un gran editor de LaTeX limpio, configurable con un buen apoyo tecla de acceso rápido y una extensa documentación de látex . Texmaker integra muchas herramientas necesarias para desarrollar documentos con LaTeX, en una sola aplicación . Tiene algunas buenas características como resaltado de sintaxis, inserción de 370 símbolos matemáticos con un solo clic, y "estructura vista" del documento para facilitar la navegación .

Answer 18

Respuesta simple: LaTeX parece exactamente lo que estás buscando.

Lo uso para escribir la documentación yo mismo. Nunca volveré a Word si tengo la opción.

Answer 19

No he tenido tiempo de probarlo, pero siempre he pensado que AsciiDoc sería bueno para este tipo de cosas.

Answer 20

Si quieres algo más sencillo que el látex, se puede echar un vistazo a ReStructured Text

Answer 21

En phc, hemos comenzado con el látex, luego se trasladó a docbook, y se han establecido (de forma permanente espero) el texto reestructurado/Sphinx.

Se eligió el látex porque somos académicos, y el látex es la herramienta de elección. Creo que no generó HTML lo suficientemente bueno.

Docbook fue elegido por su potencia, pero era muy difícil de manejar. Nos impidió escribir cualquier documentación: el código tenía que formatearse manualmente, nos olvidamos de la sintaxis y era difícil de leer. La curva de aprendizaje también fue pronunciada.

Finalmente, pasamos a reST, usando sphinx, y esa fue una gran decisión. La documentación ahora es muy fácil de escribir, y tanto PDF como HTML versions se ven hermosas (aunque el PDF podría funcionar con cierta personalización). Es muy fácil de personalizar también.

Sin embargo, lo mejor de reST es que es legible para humanos en forma de fuente. Esa es una maravillosa ventaja. He cambiado a usar reST para todas mis cosas ahora, especialmente cualquier cosa en la web (excepto, por supuesto, artículos académicos, donde sería tonto usar cualquier cosa que no sea látex).