documentation - generate - ¿Se puede usar LaTeX para producir cualquier documentación que acompañe al software?
latex software (12)
Aunque relacionado con esta pregunta sobre la utilización de LaTeX fuera de las matemáticas y la academia , me pregunto específicamente si alguien utiliza o está familiarizado con cualquiera que utilice LaTeX para generar cualquier tipo de documentación relacionada con el software. Si es así, ¿podría decir si le gusta LaTeX y los fines para los cuales lo usa? Gracias.
Después de haber usado extensivamente LaTeX y también la documentación escrita del software, diría que la fuerza de LaTeX es un sistema de tipografía muy flexible, de modo que cambiar las plantillas y el formato es muy sencillo, y que escribir matemáticas es bastante rápido. No creo que ninguna de esas fortalezas sea particularmente útil al escribir documentación, porque la documentación necesita muchas capturas de pantalla e instrucciones paso a paso.
El mayor problema que tengo con LaTeX, al menos TeXShop en la Mac, es el formato y ubicación de imágenes. Las herramientas en MS Office u OpenOffice son mucho más útiles para eso. La capacidad de cambiar el tipo de letra solo es buena cuando se publica en diferentes publicaciones; el diseño consistente de la documentación puede ser manejado fácilmente por plantillas y similares en el software de oficina.
Además, hay más personas acostumbradas al software de oficina que LaTeX, por lo que la curva de capacitación es más pequeña. Entonces, cuando llega la siguiente persona y necesita actualizar la documentación existente, puede comenzar de inmediato, en lugar de tener que aprender LaTeX.
El conjunto de herramientas Insight Segmentation and Registration ( www.itk.org ) tiene un sistema muy atractivo en el que la fuente LaTeX se incluye en los comentarios del código fuente y en realidad generan una guía de programación de varias páginas.
Existe el sistema CWEB de Knuth que usa TeX. http://www-cs-faculty.stanford.edu/~knuth/cweb.html
Lo he usado para la documentación del software y funciona bastante bien para esto. Uno de los beneficios clave es la facilidad con la documentación integrada de múltiples fuentes. Puede (por ejemplo) representar una referencia API o un diccionario de datos para LaTeX y hacer una referencia cruzada con otras partes de la especificación. Si puede poner fragmentos de LaTeX en los comentarios de la API, los XREF pueden incluso funcionar en ambos sentidos.
LaTeX también es muy bueno para mantener los índices, las entradas de TOC y otros elementos similares, por lo que la calidad del contenido del documento es mucho mejor que con herramientas como la palabra. Las referencias cruzadas, las entradas de índice y los anclajes son mucho más estables.
Muchos proyectos en la ecosfera de Python están utilizando Sphinx para producir su documentación. LaTeX es uno de los muchos formatos de salida que Sphinx puede producir. Creo que Doxygen , un motor de documentación C ++ / C / Python / Objective-C / .. también puede producir resultados LaTeX.
En general, los proyectos en los que se requiere un formato de documentación en papel o donde la documentación necesariamente contiene muchas matemáticas se benefician en gran medida de la documentación generada por LaTeX; estas son, además de la especialidad de LaTeX. LaTeX en sí mismo es un sistema de composición general, no un generador de documentación de código, por lo que recomendaría utilizar un paquete como los descritos anteriormente para generar documentación de código en LaTeX. Usar uno de estos sistemas de nivel superior simplificará en gran medida la tarea.
No he usado LaTeX desde que dejé de ser un ingeniero mecánico. Sé que se usa extensivamente para escribir papeles con matemáticas. Cualquier persona que presente un documento para su consideración por parte de una revista ASME seguramente lo usará. Lo usé para componer mi disertación y me encantó.
Pero desde entonces, no he visto nada más que Word, sin una sola excepción.
Principalmente escribo artículos académicos con LaTeX. Sin embargo, mi investigación tiene que ver con la documentación del software, por lo que realmente me ocupo de algunas de estas preocupaciones.
Lo mejor de LaTeX es que le preocupa el contenido y la estructura, no solo el diseño visual. Esto es como escribir HTML con CSS en lugar de HTML puro.
Aquí hay algunas razones por las que creo que LaTeX es útil para crear documentación:
Una razón es que lidiar con múltiples estilos es más estructurado y los estilos son más "lógicos" que "visuales". Por ejemplo, si escribe en Word, cada vez que quiera mencionar una clase u objeto, cambiará un estilo. En LateX, mientras escribo, escribo algo así como:
bla bla bla ~ / methodName {foo} bla bla ~ / className {FooBar}.
Me parece que para documentos largos, esto es útil. Puedo encontrar fácilmente mis nombres de clase, cambiarlos, etc.
Un segundo beneficio es que puedo usar macros para entidades. Por ejemplo, supongamos que tengo algún módulo que maneja alguna funcionalidad, pero que su nombre puede cambiar más adelante o que no estoy seguro de qué se trata. Puedo tener una macro llamada / ModuleForXXX, y cuando finalmente elijo un nombre o lo cambio.
Un tercer y quizás más importante beneficio es que es más fácil crear un documento desde una jerarquía de archivos en LaTeX que en un documento de Word. Normalmente tengo un archivo principal que luego incluye otros archivos, que luego incluyen otros archivos, etc. Lo veo jerárquicamente (al menos en Windows con WinEDT), y puedo reorganizar fácilmente el orden de las cosas simplemente cambiando las inclusiones. Huelga decir que también uso incluye el contenido real de fragmentos de código y texto de documentación.
LaTeX tiene varios inconvenientes: 1) Poca gente lo sabe y algunas personas que están acostumbradas a Word simplemente lo resienten. Sin embargo, para alguien que lee un PDF final, no debería importar. 2) La colocación de imágenes puede ser un poco complicado, aunque puede anular las opciones y forzar a LaTeX a escuchar sus instrucciones. 3) Funciona mejor con una configuración de monitor dual.
GNU Troff (Groff) parece ser más popular que LaTeX en la comunidad de software. Según Wikipedia , O''Reilly también lo usa para sus libros.
Ayudé a configurar LaTeX con fines de documentación en una empresa anterior. Funcionó, pero a los escritores técnicos no les gustó.
La principal queja fue que sentían que era esclavitud. Lo cual fue una buena cosa, no pudieron estropear demasiado las cosas.
Fue bastante trabajo configurar la clase de documento para que fuera la correcta y la ubicación de las imágenes nunca fue perfecta en todos los casos, pero la documentación final fue simplemente hermosa. Lo haría de nuevo si tuviera la opción.
Entonces no era un gurú de LaTeX (y todavía no lo es), pero necesitará a alguien con conocimiento en LaTeX para configurar y respaldar tal empeño ya que la mayoría de los escritores de tecnología no están interesados en aprender las entrañas de LaTeX para apoyarse.
Lo usé a veces, pero mi jefe está más interesado en los documentos de la oficina y si escribe la documentación o partes de ella, no usamos LaTeX.
Personalmente me gusta LaTeX y también la utilizo para la documentación de software donde sea apropiado y donde estoy en condiciones de decidir por mí mismo.
Algunos grandes software de código abierto crean sus documentos desde cero. El sistema de documentación de Perl (POD, una documentación similar a la del hombre) admite la exportación a LaTeX, que solía usar para imprimirlo.
Solo estoy descubriendo qué dolor es producir caracteres circunflejos ( ^ ) y tilde ( ~ ) de tamaño completo en LaTeX. Que son útiles para componer el código fuente en lenguajes como C.
Aquí hay una descripción de las contorsiones aparentemente necesarias para la tilde; Acabo de hacer una pregunta similar en ese foro sobre el circunflejo.