La documentación del código es un proceso mediante el cual un programador documenta el código. Es un término muy conocido entre los ingenieros. Si no lo hacen, conduce a una mala legibilidad del código y a un difícil mantenimiento para otros miembros del equipo.
La documentación del código es diferente de la documentación del proyecto, ya que tiene como objetivo principal cómo funciona el sistema, pero estos dos procesos tienen algo en común: los requisitos de utilizar una herramienta profesional. En este artículo, repaso algunas herramientas populares para crear documentación de código.
LaTex
LaTeX es un sistema de preparación de documentos para la composición tipográfica de alta calidad. Se utiliza con mayor frecuencia para documentos técnicos o científicos de tamaño medio o grande, pero puede utilizarse para casi cualquier forma de publicación.
¡LaTeX no es un procesador de textos! En su lugar, LaTeX anima a los autores a no preocuparse demasiado por la apariencia de sus documentos, sino a concentrarse en conseguir el contenido adecuado.
LaTeX es un sistema de composición tipográfica de alta calidad; incluye características diseñadas para la producción de documentación técnica y científica. LaTeX es el estándar de facto para la comunicación y publicación de documentos científicos. LaTeX está disponible como software libre.
No hay que pagar por usar LaTeX, es decir, No hay que pagar por usar LaTeX, es decir, no hay cuotas de licencia, etc.
Pandoc
Pandoc entiende una serie de extensiones útiles de la sintaxis de markdown, incluyendo los metadatos del documento (título, autor, fecha); notas al pie; tablas; listas de definición; superíndice y subíndice; tachado; listas ordenadas mejoradas (el número de inicio y el estilo de numeración son significativos); listas de ejemplos en ejecución; bloques de código delimitados con resaltado de sintaxis; comillas inteligentes, guiones y elipses; markdown dentro de bloques HTML; y LaTeX en línea. Si se desea una compatibilidad estricta con markdown, todas estas extensiones pueden desactivarse.
Hay muchas formas de personalizar Pandoc para que se adapte a sus necesidades, incluyendo un sistema de plantillas y un potente sistema para escribir filtros.
Pandoc incluye una biblioteca Haskell y un programa de línea de comandos independiente. La biblioteca incluye módulos separados para cada formato de entrada y salida, por lo que añadir un nuevo formato de entrada o salida sólo requiere añadir un nuevo módulo.
Pandoc es software libre, publicado bajo la GPL.
Markdown
Markdown es una herramienta de conversión de texto a HTML para escritores web. Markdown le permite escribir utilizando un formato de texto plano fácil de leer y escribir, y luego convertirlo en XHTML (o HTML) estructuralmente válido.
El objetivo primordial del diseño de la sintaxis de formato de Markdown es hacerlo lo más legible posible. La idea es que un documento con formato Markdown sea publicable tal cual, como texto plano, sin que parezca que ha sido marcado con etiquetas o instrucciones de formato. Mientras que la sintaxis de Markdown ha sido influenciada por varios filtros existentes de texto a HTML, la mayor fuente de inspiración para la sintaxis de Markdown es el formato del correo electrónico de texto plano.
LiveEdu
LiveEdu le permite transmitir su documentación de código y crear «documentación de código de vídeo».
Education Ecosystem es un ecosistema de aprendizaje descentralizado que enseña a los profesionales y estudiantes universitarios cómo construir productos reales. Se puede describir nuestro producto como un híbrido de Pluralsight y Twitch. Estamos construyendo el mayor ecosistema de aprendizaje del mundo para temas tecnológicos del futuro como la inteligencia artificial, la ciberseguridad, el desarrollo de juegos, la ciencia de los datos, las criptomonedas y la programación. El Ecosistema Educativo está basado en vídeos y cada proyecto contiene vídeos, un esquema estructurado del proyecto, un repositorio del proyecto y recursos descargables. Los usuarios pueden clonar los recursos del proyecto desde el Git de Education Ecosystem y ejecutar las aplicaciones en su máquina local.
Sphinx
Sphinx es una herramienta que facilita la creación de documentación inteligente y hermosa, escrita por Georg Brandl y licenciada bajo la licencia BSD.
Fue creada originalmente para la documentación de Python, y tiene excelentes facilidades para la documentación de proyectos de software en una gama de lenguajes. Estas son algunas características:
- Formatos de salida: HTML (incluyendo la Ayuda HTML de Windows), LaTeX (para versiones PDF imprimibles), ePub, Texinfo, páginas de manual, texto plano.
- Amplias referencias cruzadas: marcado semántico y enlaces automáticos para funciones, clases, citas, términos de glosario y piezas de información similares.
- Estructura jerárquica: fácil definición de un árbol de documentos, con enlaces automáticos a hermanos, padres e hijos.