¿Qué es la documentación del software? Tipos y mejores prácticas para comenzar

Si desea que los desarrolladores y usuarios finales obtengan el mayor valor posible de su software, debe crear documentación de software de alta calidad.

Pero, ¿qué es realmente la documentación del software y cómo puede crearla para su proyecto?

En esta publicación, profundizaremos en todo lo que necesita saber sobre la documentación del software, incluido lo siguiente:

• ¿Qué es la documentación del software?
• Los diferentes tipos de documentación de software (con ejemplos)
• Cómo publicar la documentación de su software (las mejores herramientas)
• Algunas mejores prácticas para crear documentación de software de calidad

¡Vamos a profundizar en!

¿Qué es la documentación del software?

La documentación del software es contenido que ayuda a los usuarios finales, desarrolladores y/o sus empleados a comprender su software y usarlo para lograr sus objetivos de manera efectiva.

Por lo general, publicará la documentación del software en su sitio web. Luego, las personas pueden acceder a él para obtener más información sobre su software y cómo funciona.

Dentro de esa amplia definición de documentación de software, existen diferentes tipos de documentación de software. Vamos a discutir eso a continuación.

Los diferentes tipos de documentación de software

Puede dividir aproximadamente los diferentes tipos de documentación de software en algunas categorías amplias.

La primera consideración es a qué tipo de persona está destinada la documentación:

• Documentación del usuario : esta es la documentación que ha creado para el usuario final del producto. Les ayuda a comprender cómo utilizar su software desde la perspectiva de un usuario habitual, que puede o no tener conocimientos técnicos especiales.
• Documentación del desarrollador : se trata de documentación de software más técnica que ha creado para los desarrolladores, como la documentación de la API.

La segunda consideración es si la documentación está destinada a audiencias externas o internas:

• Documentación de software externo : se trata de documentación pública que ha creado para ayudar a sus usuarios.
• Documentación interna del software : esta es documentación privada que ha creado para sus empleados para ayudarlos a trabajar de manera más efectiva y comprender los detalles clave.

Por ejemplo, puede tener un conjunto de documentación de desarrollador para sus equipos internos para ayudar a trabajar en el software y otro conjunto de documentación de desarrollador de cara al público para desarrolladores externos.

Analicemos estos tipos de documentación de software con un poco más de detalle...

Ejemplos de documentación de software para la documentación del desarrollador

• Documentación de la API : muestre a los desarrolladores cómo interactuar con la API de su software.
• Léame : presente su software y explique lo que hace; por lo general, es lo primero que lee la gente.
• Notas de la versión : documente las nuevas versiones de su software, incluidos los cambios importantes.
• Documentación de la arquitectura : muestre la estructura de su software, lo que podría incluir diagramas.
• Documentación del modelo de datos : documente las diferentes estructuras de datos en su software, incluidas las relaciones entre las diferentes estructuras de datos.
• Documentación de procesos : documente procesos clave, como informes de errores, hojas de ruta, control de calidad, protocolos de prueba, etc.

Para ver un ejemplo de documentación de software real de documentos centrados en desarrolladores, puede consultar la documentación de "Desarrolladores" de Gravity Forms que cubre varios temas, como:

• Ganchos de PHP (para WordPress)
• Objetos de datos
• API de PHP
• Base de datos
• API REST

Por ejemplo, así es como se ve la documentación de la API REST:

Ejemplos de documentación de software para la documentación del usuario

• Guía de inicio : muestre a los usuarios cómo comenzar a usar su software rápidamente.
• Tutoriales para casos de uso específicos : tutoriales más específicos para realizar tareas específicas.
• Glosarios de términos/manuales de referencia : ayudan a los usuarios a comprender los términos y detalles clave.
• Preguntas frecuentes : responda las preguntas más frecuentes.

Para ver un ejemplo real de cómo podría verse una documentación de software más centrada en el usuario, puede consultar el mismo ejemplo de Gravity Forms anterior.

Si observa los artículos más centrados en el usuario de Gravity Forms, verá muchos tutoriales paso a paso sobre cómo realizar tareas utilizando la interfaz del software, junto con glosarios y explicaciones de las funciones clave.

En comparación con la documentación del software para desarrolladores, verá más capturas de pantalla y explicaciones en lenguaje sencillo y muchos menos bloques de código.

Cómo publicar documentación de software: las tres mejores herramientas de documentación de software

Para publicar la documentación de su software en su sitio web, necesitará una herramienta de documentación de software dedicada o algún tipo de sistema de gestión del conocimiento.

En esta sección, cubriremos rápidamente algunas de las mejores herramientas de documentación de software. Luego, en la siguiente sección, repasaremos algunas de las mejores prácticas para crear documentación de calidad.

Si desea una mirada más profunda aquí, puede leer nuestras guías completas sobre las mejores herramientas de documentación y el mejor software de documentación técnica.

Base de conocimiento heroica

Heroic Knowledge Base es un complemento de documentación y base de conocimientos para el popular software de código abierto WordPress.

Con Heroic Knowledge Base, puede hospedar su propia documentación y mantener el control total, mientras sigue accediendo a todas las funciones que necesita para crear una documentación de software eficaz.

Estas son algunas de las características principales que obtiene con Heroic Knowledge Base:

• Editor de contenido flexible , que incluye bloques integrados para llamadas y otros detalles de estilo importantes.
• Tabla de contenido automática para que los usuarios puedan ver rápidamente qué contenido se cubre en un artículo de documentación y saltar a secciones específicas.
• Control de revisiones e historial de versiones a través del sistema de revisiones nativo de WordPress.
• Funciones de descubrimiento de contenido que incluyen búsqueda Ajax en tiempo real con sugerencias en vivo, categorías y más.
• Sistema de comentarios de los usuarios que permite a las personas calificar los artículos como útiles o inútiles y compartir comentarios.
• Análisis de búsqueda para que pueda ver lo que buscan los usuarios, así como los términos de búsqueda que arrojan cero resultados.
• Widget de respuestas instantáneas que permite a los usuarios buscar y acceder a la documentación del software desde cualquier parte de su sitio.

Debido a que Heroic Knowledge Base y WordPress son autohospedados y de código abierto, también puede modificar su configuración según sea necesario.

Puede hacerlo público o restringir el acceso a su documentación con varias tácticas, como contraseñas, cuentas de usuario, direcciones IP, una intranet y más.

Heroic Knowledge Base comienza en solo $ 149 por año.

Leer los documentos

Read the Docs es una herramienta de documentación que se enfoca en ayudarlo a crear documentación para desarrolladores.

Si está enfocado específicamente en crear documentación técnica para desarrolladores, puede ser otra buena opción a considerar.

Puede administrar su contenido y el historial de revisión con Git y luego implementar sus documentos en una interfaz de usuario.

Estas son algunas de las otras características notables en Read the Docs:

• Análisis incorporado para ver lo que sus usuarios están leyendo y buscando.
• Admite múltiples compilaciones simultáneas , lo que puede ser útil si ofrece varias versiones de su software, por ejemplo, un conjunto de documentación para la versión 1.0 y otro para la versión 2.0.
• Exporte documentación en diferentes formatos, incluidos PDF, HTML y epub.
• Sugerencias de búsqueda en vivo para ayudar a los usuarios a encontrar documentos.

Read the Docs es de uso gratuito si tiene un proyecto de software de código abierto.

Para los productos de software comercial, hay un servicio de pago Read the Docs for Business que comienza en $50 por mes.

GitBook

GitBook es otra herramienta de documentación de software técnico que le permite administrar su documentación usando Git, con soporte para repositorios de GitHub y GitLab.

O, si no quiere usar Git, GitBook también le permite crear su documentación usando un editor de texto o importarla desde archivos Markdown o .doc.

Aquí hay algunas otras características notables que ofrece GitBook:

• Control de versiones para realizar un seguimiento de las revisiones y el historial de versiones.
• Edición en equipo en vivo , que es útil si necesita que varios autores colaboren en los artículos.
• Organice los artículos usando "espacios" y "colecciones": cada espacio puede tener varias colecciones en su interior.
• Opción de exportación de PDF para que los usuarios puedan exportar fácilmente su documentación como una descarga de PDF.

GitBook es gratuito para organizaciones sin fines de lucro o proyectos de código abierto.

Para proyectos de software comercial, GitBook comienza en $8 por usuario por mes, con un mínimo de 5 usuarios. Eso significa que la tarifa mensual más barata es de $ 40 por mes.

Mejores prácticas para crear documentación de software

Para finalizar, profundicemos en algunas de las mejores prácticas de documentación de software para ayudarlo a crear una documentación efectiva.

Piense en los objetivos y necesidades de los usuarios

Cuando está escribiendo un artículo de documentación de software, es importante comenzar respondiendo algunas preguntas básicas:

• ¿Quién es el usuario para el que estás escribiendo?
• ¿Qué está tratando de lograr el usuario?
• ¿Qué nivel de conocimiento técnico tiene el usuario?

Conocer las respuestas a estas preguntas te ayudará a comprender qué contenido cubrir y cómo estructurar el artículo de la manera más óptima.

Por ejemplo, supongamos que ofrece un software de programación de redes sociales y está escribiendo un artículo que ayuda a los administradores de redes sociales a programar su primera publicación en redes sociales.

Al escribir la documentación de su software, querrá centrarse en mostrar la forma más sencilla para que un usuario final normal logre ese objetivo.

Si también ofrece una API para permitir que los desarrolladores configuren sus propias integraciones, probablemente querrá cubrir eso en un artículo diferente ( aunque puede mencionar y enlazar a ese método ).

Incluir documentación de software en el proceso de desarrollo

Cuando está creando documentación de software, es fácil caer en la trampa de esperar hasta que se complete un proyecto para documentarlo.

Sin embargo, esto puede conducir rápidamente a una deuda de documentación porque es posible que envíe nuevas funciones o cambios antes de que se hayan documentado.

Para evitar esto, haga que la documentación del software sea una parte consciente del ciclo de desarrollo del software. Si aún no se ha documentado una nueva característica o producto, no está listo para enviarse, incluso si el código en sí está terminado.

Al hacer de la documentación un requisito fundamental del proceso de desarrollo de software, puede asegurarse de que todo lo que envíe vaya acompañado de la documentación adecuada.

Use formato y estilo consistentes

Para ayudar a las personas a trabajar de manera más eficaz con la documentación de su software, es importante que utilice un formato y un estilo coherentes en toda su documentación.

El uso del mismo formato permite a los lectores aprender cómo está estructurada la documentación de su software, lo que les facilitará el acceso rápido a la información que necesitan.

Para ayudar a lograr esta coherencia, es posible que desee crear una guía de estilo de documentación de software dedicada.

Su herramienta de administración de documentación de software también puede incluir funciones para ayudarlo a lograr un estilo uniforme.

Por ejemplo, el complemento Heroic Knowledge Base incluye llamadas prediseñadas para resaltar información o advertencias clave. Al usarlos, puede garantizar un formato uniforme en toda su documentación.

Use expertos para escribir documentación técnica

Para la documentación de software orientada al usuario, es posible que no necesite expertos en la materia para escribir el contenido.

Sin embargo, para una documentación de software más técnica, como la documentación de la API centrada en el desarrollador, es probable que desee asignar a alguien con los conocimientos técnicos relevantes para que escriba esos documentos.

Este podría ser un escritor técnico dedicado con experiencia en el dominio, si su organización tiene los recursos para contratar para ese puesto. O bien, podría ser uno de sus desarrolladores.

Lo importante es que el escritor comprenda los aspectos técnicos de su software a un nivel lo suficientemente profundo como para explicárselo a otros usuarios técnicos.

Facilite que las personas descubran contenido (Búsqueda/Filtro)

A medida que crezca su biblioteca de documentación, será más difícil para los usuarios encontrar los artículos de documentación que satisfagan sus necesidades.

Para tratar de evitar este problema, querrá concentrarse en mejorar la capacidad de detección de la documentación de su software.

Una primera estrategia es dividir su documentación por tipo.

Por ejemplo, normalmente querrá separar la documentación del usuario final de la documentación del software del desarrollador.

Dentro de eso, también puede usar categorías para dividir aún más los artículos. Puede usar categorías basadas en funciones, casos de uso, complementos, etc., lo que tenga sentido lógico para su producto de software.

De acuerdo con el mismo ejemplo anterior de Gravity Forms, puede ver que Gravity Forms divide su documentación de usuario final por tipos de funciones.

Otra característica útil de descubrimiento son las sugerencias de búsqueda en vivo. Los usuarios pueden comenzar a escribir una consulta relevante en el cuadro de búsqueda y ver instantáneamente los artículos de documentación que coinciden con esa consulta.

Muchas herramientas de documentación incluyen una funcionalidad de búsqueda en vivo incorporada, incluida la Base de conocimiento heroica.

Mantenga actualizada la documentación de su software

Debido a que su software siempre está cambiando, la documentación de su software siempre será un trabajo en progreso.

A medida que cambien las cosas en su software, deberá actualizar rápidamente su documentación para reflejar esos cambios.

De lo contrario, su documentación no solo "no será útil", sino que podría estar creando confusión en sus usuarios.

Para asegurarse de que se realicen estas actualizaciones, querrá asignar personas específicas para que se hagan cargo de la documentación y el proceso de actualización. De esa manera, no hay ambigüedad sobre quién es responsable de mantener todo correcto.

Utilice los comentarios de los clientes para mejorar su documentación

Además de tener su propio equipo trabajando en la revisión y actualización de la documentación de su software, también querrá tener en cuenta los comentarios de los clientes.

Los clientes pueden proporcionar información valiosa sobre cuán útil (o potencialmente inútil) es un determinado artículo de documentación de software, junto con detalles sobre cómo podría mejorarlo.

Para automatizar el proceso de comentarios de los clientes, querrá buscar una herramienta de administración de documentación que incluya funciones integradas para los comentarios de los clientes.

Por ejemplo, el complemento Heroic Knowledge Base permite a los usuarios calificar un artículo como útil o inútil y, opcionalmente , proporcionar comentarios de forma libre.

Luego puede ver toda esta información desde su tablero para detectar rápidamente los artículos de documentación que necesita mejorar.

Comience a documentar su software hoy

La documentación del software lo ayuda a usted y a sus clientes a trabajar de manera más efectiva y obtener más valor de su software.

Hay diferentes tipos de documentación de software, por lo que querrá pensar en qué tipos se ajustan a las necesidades de su proyecto de software.

Es posible que tenga documentación diferente para equipos internos o externos, así como para diferentes tipos de clientes, como desarrolladores y usuarios finales.

Para crear documentación efectiva, querrá seguir las mejores prácticas de esta publicación.

Para publicar esa documentación, puede utilizar una herramienta de código abierto como Heroic Knowledge Base, que se basa en el potente software de WordPress.

Obtendrá la flexibilidad y propiedad de una plataforma autohospedada, con todas las características y funciones que necesita para publicar documentación de software de alta calidad.

Si desea obtener más información, haga clic aquí para ir a Heroic Knowledge Base.