18 Herramientas de documentación de software que hacen el trabajo duro por usted

🟢 Material extra: Lista de comprobación del flujo de trabajo de Git para simplificar &la gestión de versiones

Sin documentación, el software no es más que una caja negra. Y las cajas negras no son ni de lejos todo lo útiles que podrían ser porque su funcionamiento interno está oculto a quienes lo necesitan a la vista.

La documentación del software convierte su software en una caja de cristal al explicar a los usuarios y desarrolladores cómo funciona o se utiliza.

Probablemente hayas visto la documentación antes, pero si necesitas un repaso, aquí tienes un ejemplo de la API de Slack:

Como puedes ver, Slack explica todo sobre su API con un detalle insoportable. Cualquier página relacionada está enlazada, hay una barra lateral con temas de fácil acceso y capturas de pantalla de lo que el usuario puede esperar ver.

Para explicar esto con más detalle, vamos a cubrir los siguientes temas en este post de Process Street:

• ¿Qué es la documentación de software?
• Opciones de alojamiento de documentación de software
• Herramientas de escritura para la documentación de software
• Palabras finales sobre la documentación de software

Comencemos.

¿Qué es la documentación del software?

«La documentación en la ingeniería del software es el término general que abarca todos los documentos y materiales escritos que tratan sobre el desarrollo y el uso de un producto de software» – Prototype.io, Software Documentation Types and Best Practices

Todas las piezas de software deben tener algún tipo de documentación que explique, en detalle, qué es el producto, cómo funciona y por qué funciona de esa manera.

«Si no está documentado, no existe» – Sitepoint, A Guide to Writing Your First Software Documentation

Como desarrollador, su principal objetivo es escribir el mejor código posible. Quieres que tu código sea el mejor de su clase, fácil de leer, fácil de usar, y quieres que ocurran grandes cosas como resultado de él. ¿Verdad?

Pero sin documentar lo que has hecho y por qué lo has hecho:

• Nadie más puede usar tu código sino tú

Sin documentación, nadie entenderá lo que has hecho y por qué lo has hecho. Será increíblemente difícil, casi imposible, que otra persona coja tu código y lo trabaje. Incluso podrían desecharlo y empezar de nuevo, ya que, en algunos casos, eso sería más rápido que tratar de averiguar lo que has hecho y por qué.

• No puedes actualizarlo o mejorarlo

¿Puedes recordar lo que cenaste el sábado, hace tres meses? A menos que seas un completo animal de costumbres, lo más probable es que no puedas. Así que es justo decir que probablemente no recordarás el código que escribiste, dos, tres, cuatro meses después de haberlo hecho. Si no puedes recordar las razones detrás de tus decisiones de codificación, entonces te costará ser capaz de actualizarlo o mejorarlo.

A pesar de esto, la documentación del software es a menudo una tarea que se apresura, se hace mal, se le quita prioridad o se olvida totalmente.

Antes de empezar a hablar de qué herramientas se pueden utilizar para escribir la documentación del software, tenemos que pensar en una manera de asegurarse de que la tarea se hace en primer lugar.

Aquí es donde Process Street puede ayudar.

Process Street es una pieza de software de gestión de procesos de negocio (BPM) que se puede utilizar para crear, gestionar y seguir los procesos.

Más sobre lo que es Process Street más tarde, por ahora, permítame mostrarle cómo puede utilizarlo como una herramienta para ayudarle a encajar la documentación de software en cada proyecto de desarrollo de software en el que trabaja.

Abajo hay un ejemplo de una plantilla de Proceso de Despliegue de Software pre-hecha. Esta plantilla fue creada para ayudar a los ingenieros de software y programadores a desplegar su software de la mejor manera posible.

¡Haga clic aquí para acceder al Proceso de Despliegue de Software!

Para obtener esta plantilla, inicie sesión y añádala a su panel de control, o suscríbase a una prueba gratuita.

Esta plantilla es un ejemplo perfecto de un proceso que puede seguir cada vez que quiera desplegar una pieza de código nueva o actualizada.

Tiene pasos claros que le guiarán a través de todo el proceso de despliegue, desde la configuración de un entorno de ensayo hasta la puesta en marcha de los cambios. Estos pasos se asegurarán de que no se pierda nada y que todo el proceso vaya sin problemas cada vez.

Hemos diseñado esta plantilla para ser utilizada como una guía para ayudarle a crear un proceso de despliegue que funcione para usted. Cada empresa es diferente, cada proyecto de software es diferente, y cada proceso de despliegue es diferente.

Puede editar este proceso y añadir las tareas que sean relevantes para usted, su empresa y su proyecto.

Lo que me lleva de nuevo a la documentación del software; podría añadir «documentación del software» como una tarea. De esta manera, cualquier persona que trabaje en el proceso de despliegue de software será recordado y animado a completar esto, como parte del proceso.

Tengo algunas plantillas de proceso más pre-hechas que podrían ser de utilidad para usted, que voy a incluir al final de este post.

Antes de llegar a eso, vamos a ver dónde puede almacenar su documentación de software.

Opciones de alojamiento de documentación de software

No es bueno tener sólo un montón de archivos de texto viviendo en su computadora. Tienen que ser accesibles para los desarrolladores y los usuarios, lo que probablemente va a hacer mediante el alojamiento de los documentos en Internet, ya que no es la década de 1980.

Process Street (para uso interno)

Para la formación de nuevos desarrolladores y mantener su documentación viviendo todos en el mismo lugar, Process Street es una opción sólida para la documentación de software.

Primero, podrías crear un proceso para escribir tu documentación, para asegurarte de capturar todos los detalles correctos y hacerla lo más útil posible.

Usando las siguientes características fáciles de usar, puede entonces escribir y almacenar su documentación en un solo lugar:

• Widgets de imagen
• Widgets de texto
• Widgets de vídeo
• Widgets de archivo
• Subtareas
• Widgets de correo electrónico
• Widgets de archivo

Al almacenar su documentación dentro de Process Street significa que todos los miembros de la empresa pueden acceder a ella. Puede compartirla con otros, enviarla para su aprobación, establecer recordatorios para revisarla y actualizarla fácilmente.

Compruébelo:

Si se puede documentar, se puede documentar en Process Street.

Inscríbete en una prueba gratuita aquí y pruébalo.

Read The Docs

Es notable que Read The Docs sea gratis cuando ves todo lo que puede hacer. Al igual que GitHub, puedes crear todo el material de código abierto que quieras y que se indexe abiertamente en el sitio, pero te va a costar si quieres que los documentos sean privados e internos para tu empresa. Para nuestros propósitos, es probable que usted va a estar bien con tener los documentos disponibles para los usuarios en la web.

La razón por la que Read The Docs es tan bueno es que se puede importar sin esfuerzo la documentación de cualquier sistema de control de versiones, incluyendo Git, Mercurial, Subversion, y Bazaar. También es compatible con webhooks para que los documentos se construyan automáticamente cada vez que se confirma el código.

Consulta su guía de inicio para tener una idea de cómo funciona y cómo se comportan tus documentos cuando se alojan allí.

GitHub (& GitHub Pages)

Si estás usando GitHub para gestionar el control de versiones de tu software, tienes, como mínimo, un archivo README.MD en el repositorio. Para usar GitHub para documentar tu software, como millones de personas han hecho en el pasado, simplemente rellena ese README con markdown.

Un gran ejemplo es el repositorio t de sferik, capturado aquí:

Si quieres algo más que una hoja de texto formateada, puedes aprovechar la herramienta Pages de GitHub (obtienes una página web gratuita + alojamiento con cada cuenta de GitHub, e incluso puedes dirigir un dominio personalizado a ella). Pages incluso tiene temas predeterminados de gran aspecto que hacen que tu documentación tenga un aspecto profesional.

Arriba está la documentación de atom.io para Electron alojada en GitHub. Es una opción inteligente porque funciona automáticamente con el control de versiones de GitHub, al igual que el resto de su software. Vea el repositorio del sitio aquí.

Dropbox Paper (para uso interno)

Para el uso interno de documentación de software, Dropbox Paper es una excelente opción. Al igual que su predecesor Hackpad, puedes utilizarlo para crear un wiki privado para los empleados. Puedes enlazar documentos entre sí, insertar bloques de código, imágenes y saltos de página, tal y como exigirías a cualquier herramienta de documentación.

Como puedes ver en los comentarios de la derecha, también puedes utilizarlo para pasar por procesos de aprobación y colaborar en la creación de documentación. En general, es una gran herramienta para el desarrollo interno y la creación de documentación, tal vez con la vista puesta en publicarla más tarde, o simplemente mantenerla para uso interno.

Atlassian REST API Browser (para el uso de la API)

El REST API Browser (RAB) de Atlassian está incluido en JIRA Server, Confluence Server y las instancias de Stash por defecto. Está construido para descubrir APIs disponibles para su uso en entornos de JIRA/Confluence, y también un lugar para alojar su documentación. Si, por supuesto, su API encaja en el proyecto de ley.

Documente su API utilizando esta herramienta para dar a su API compatible con JIRA/Confluence una mayor exposición. Consulta aquí la documentación de Atlassian para hacerlo.

Tettra (para uso interno)

Tettra es una especie de software de base de conocimientos donde puedes documentar tu desarrollo, o cualquier cosa.

Utilizamos Tettra internamente en Process Street para un montón de casos de uso. Día a día, utilizo Tettra para tener un único lugar donde todos mis procesos están documentados para que nunca me olvide de cómo uno se relaciona con otro o cómo las diversas automatizaciones que hemos construido se han configurado.

Tettra es grande si usted está buscando para crear una biblioteca de tipos. Esto significa que es brillante para la documentación de software o incluso sólo como un wiki interno para su empresa.

Dado que Tettra está diseñado específicamente para la gestión del conocimiento, viene con una serie de otras características de apoyo también. Por ejemplo, puede hacer sugerencias en cuanto a lo que el contenido adicional o secciones que puede agregar para dar una imagen más completa de su org y cómo las cosas encajan entre sí.

Puede ver un pequeño video aquí para cómo un equipo de desarrollo podría mirar para usar Tettra: How Product & Engineering Teams Use Tettra.

O bien, puedes ir aquí para leer sobre cómo usamos Tettra junto a Process Street: Automatización de flujos de trabajo y listas de comprobación: Process Street Case Study.

¡Consúltalo!

Apiary (para uso de la API)

Además de ser un lugar donde viven las abejas, Apiary es un host dedicado a la documentación de la API. Escribe en markdown, añade llamadas simuladas a la API y Apiary lo recopila en algo como lo que ves a continuación:

Cualquiera puede probar la API sin tener que entrar en la aplicación o programar realmente una llamada, lo que hace que sea una forma súper accesible de compartir tu API, documentarla en profundidad y presumir de lo que puede hacer.

Hemos hablado de dónde almacenar la documentación de tu software, ahora es el momento de ver cómo escribirla.

Herramientas de escritura para la documentación del software

La documentación del software se escribe a menudo en markdown para permitir los hipervínculos y el formato mientras se mantiene en texto plano para que pueda vivir junto a los archivos de código en el control de versiones. Esto significa que muchas de mis opciones para las herramientas de escritura son simples editores markdown que hacen la experiencia de escritura agradable. Además, también hay un par de soluciones muy eficaces que no son markdown.

MarkdownPad (Windows)

Con una versión gratuita y otra premium – ambas con un montón de grandes características – MarkdownPad es el editor markdown más popular para Windows. Está optimizado para publicaciones en blogs, sitios web, artículos, READMEs y, por supuesto, documentación de software.

Puedes obtener MarkdownPad de forma gratuita, o conseguir la versión premium por 14,95 dólares.

iA Writer (Mac)

iA Writer es un editor de markdown simple y hermoso con una función de biblioteca que significa que puedes referenciar fácilmente otros documentos en la barra lateral. Le faltan los enlaces internos entre los documentos como se espera que haya en los documentos de software, pero siempre se puede hacer un pase en esos cuando está en su forma final (es decir, si va a terminar en el Internet en un sitio).

Si usted escribe toda su documentación en una, página dividida, puede utilizar anclas de salto de página para ayudar a los usuarios a navegar.

iA Writer cuesta 9,99 dólares en la Mac App Store.

Profs Knowledge Base

Profs Knowledge Base es una pequeña herramienta fantástica para todas las etapas de la creación de documentos; desde la escritura y la edición, hasta la personalización, la configuración de flujos de trabajo y la publicación. Puedes añadir multimedia, importar contenido existente de documentos de Word, PDF o PPT, guardar múltiples versiones del documento y restaurarlas cuando sea necesario.

Pero la verdadera belleza de esta herramienta reside en su facilidad de uso. Cualquiera y todo el mundo puede utilizarlo para construir la documentación de software. Tanto si llevas años documentando software como si acabas de empezar, es una herramienta increíblemente sencilla y fácil de usar.

Profs es de uso gratuito, o puedes actualizarte al paquete premium que cuesta 112 dólares al mes.

SimpleMDE (navegador)

Aunque técnicamente puedes escribir markdown en cualquier editor de texto porque es una forma de formatear texto plano, no estrictamente una ‘herramienta’, ¡no te sorprenderá que también sea posible en tu navegador! SimpleMDE es un editor de markdown funcional construido en JavaScript y un proyecto de código abierto para aprender y adaptar para su propio uso, si es necesario.

¡SimpleMDE es 100% gratuito! Obtenga la fuente en GitHub aquí.

Editores reStructuredText

Markdown es uno de los dos lenguajes más utilizados para escribir documentación de software, pero hay otro que no hemos visto hasta ahora, y es reStructuredText. Es muy similar a markdown, pero vale la pena aprender para fines de documentación de software.

Docutils, el creador de reStructuredText, ha reunido una lista de editores de reStructuredText aquí, que incluye:

El punto de reStructuredText es que es fácil convertir entre diferentes formatos, especialmente de texto plano a un sitio web estático. Ver más información aquí.

Herramientas para generar documentación automáticamente a partir del código fuente

No hay nada como el toque humano cuando se trata de documentación (está claro en los docs de Slack y Giphy, por nombrar un par). Sin embargo, como punto de partida (especialmente para las bibliotecas de fuentes enormes), es mejor generar la documentación esquelética de forma automática. Esto funciona analizando las funciones y los comentarios del código fuente, y hay algunas opciones diferentes dependiendo del idioma:

Antes de que te lances a confiar únicamente en la generación automática, te sugiero que leas este hilo de StackExchange que sopesa los pros y los contras.

Palabras finales sobre la documentación del software

Hay un montón de soluciones extravagantes, arreglos rápidos y herramientas que son (honestamente) casi idénticas. Lo que importa al final es que

Lo que más importa, al final, es que:

a) escribas la documentación del software para cada pieza de software que construyas
b) la escribas de forma exhaustiva y la alojes en algún lugar al que el usuario pueda acceder

Mencioné antes que tenía unas cuantas plantillas más de procesos de desarrollo que quizá te interese consultar?

Pues aquí están…

Plantillas de procesos de desarrollo de Process Street

Antes de darte estas plantillas, déjame explicarte un poco más qué es Process Street.

Así que sabemos que Process Street es una lista de control superpotente. Es una pieza de software que te ayudará a crear y gestionar procesos.

Pero espera, ¡hay más en Process Street que eso!

Mira este vídeo de introducción para saber a qué me refiero:

Así que ya ves, no sólo puedes crear una plantilla de proceso de desarrollo y ejecutar listas de control individuales de esto cada vez que necesites completar el proceso de desarrollo, sino que puedes personalizarla usando estas características extra

• Parar tareas
• Fechas de vencimiento dinámicas
• Permisos de tareas
• Lógica condicional
• Tareas de aprobación
• Embedir widget
• Asignación de roles

Asignar tareas, obtener la aprobación, imponer un orden en el que se completen las tareas, y puedes conectar el proceso a miles de apps a través de Zapier, webhooks o integración con la API.

Mira este seminario web sobre nuestras funciones más recientes y descubre cómo puedes sacarles el máximo partido:

Con todo esto en mente, eche un vistazo a las siguientes plantillas prediseñadas:

Lista de comprobación de auditoría de seguridad de la red

Esta plantilla puede ser utilizada por un gestor de riesgos o un profesional de TI equivalente para evaluar una red en busca de vulnerabilidades de seguridad.

¡Haga clic aquí para acceder a la lista de comprobación de auditoría de seguridad de la red!

Lista de comprobación de mantenimiento mensual del sitio web

Utilice esta lista de comprobación de mantenimiento mensual del sitio web para optimizar la velocidad de carga de su sitio, escanear en busca de vulnerabilidades y revisar su visibilidad en las búsquedas.

¡Haga clic aquí para acceder a la lista de comprobación de mantenimiento mensual del sitio web!

Tutorial de pruebas de software

Este proceso puede utilizarse para gestionar todo un proyecto de desarrollo de software de principio a fin, incluyendo el diseño, la gestión de clientes y también las comprobaciones posteriores al lanzamiento.

Pulsa aquí para acceder al Tutorial de Pruebas de Software

Y ahí lo tienes.

Ahora eres libre de usar lo que te haga la vida más fácil. Espero que encuentres tu nueva herramienta favorita en esta lista.