Terminando la serie de artículos sobre generación de documentación, revisaremos el proceso de instalación y utilización del software Sphinx. Para la elaboración de la documentación se utiliza el lenguaje RestructuredText y una serie de librerías de Python. A continuación se especifica el software que va a hacer utilizado.
Python
Lenguaje de programación base para la utilización de los software Sphinx y Rst2Pdf
Sphinx
Es un generador de documentación que convierte texto reestructurado en HTML y otros
formatos como PDF.
Sphinx
Ver artículo completo »
Continuando con la serie de artículos relacionados con la construcción de manuales de usuario, hoy revisaremos la tecnología empleada para hacerlo. En primer lugar revisaremos en que casos se debería utilizar cada una de las herramientas.
Debería usar RestructuredText si voy a:
- Generar documentación en varios formatos (Por ejemplo HTML y PDF). También es posible convertir Latex a HTML e incluso PDF a HTML, pero su soporte no es tan bueno como el que proporciona un framework como Sphinx.
- Manuales de Usuario.
- Cotizaciones.
- Artículos.
Debería usar Latex si voy a:
- Hacer un trabajo de grado o un libro largo.
- Hacer un documento o publicación científica matemático. También se puede hacer a través de Rest utilizando un plugin que utiliza las librerías matemáticas de Latex.
- Presentaciones. Tal vez en un futuro reevalúe esto, pero hay que destacar el poder de la clase beamer de Latex.
- Manuales de Usuario.
- Cotizaciones.
- Artículos.
Debería usar un Procesador de texto si voy a:
- Hacer una carta, un memorando o un documento corto en general. Esta la ventaja de no tener que compilar, por lo que en un documento de una o dos hojas sin formato podría ser más rápido utilizar un procesador de texto.
- Ojalá que para nada más.
Como se pudo apreciar, tanto RestructuredText como el Latex, se pueden usar para generar cualquier tipo de documentación, lo que buscaremos resolver a continuación es ¿en dónde radica la diferencia?
Ver artículo completo »
Ingenio Sólido como empresa desarrolladora de hardware y software esta constantemente elaborando documentación técnica y manuales de usuario para sus productos. Para nosotros la documentación se relaciona directamente con los procesos de desarrollo, estandarización y soporte. Una buena documentación agiliza el proceso de adaptación de tecnologías empleadas en otros proyectos y el desarrollo de nuevas tecnologías, permite la estandarización de los procesos de diseño electrónico y programación y disminuye la demanda de soporte básico por parte de los clientes.
Teniendo en cuenta la gran cantidad de documentación a elaborar, procesadores de texto como Open Office Writer, Google Docs o Microsoft Word no proveen la rapidez de construcción ni los resultados que nuestros estándares de calidad exigen. Por esta razón Ingenio Sólido ha optado por utilizar otras herramientas de elaboración de documentación que en principio pueden parecer más complejas de utilizar pero que a largo plazo disminuye el proceso a menos de la mitad y que ofrece unos resultados realmente sorprendentes.
En esta serie de artículos, se establecerá una estructura guía para manuales de usuario y se explicará el proceso de instalación y uso de los lenguajes para construcción de documentación RestructuredTex y Latex.
En la primera parte se revisará el proceso de estructuración de un manual de usuario, y se mostrarán algunos ejemplos de documentación.
Manual de Usuario
Ver artículo completo »
