Los equipos de producto y software comparten un problema común: la documentación¶

La documentación de producto se refiere a manuales y guías orientados al usuario que explican el flujo de trabajo y la interfaz de un producto. ¿Cómo puede un usuario promedio ser productivo con este producto? En este sentido, la documentación de producto podría usarse para productos de software.

La documentación de software se refiere a las tecnologías subyacentes, requisitos previos y atributos configurables de un producto de software. ¿Cómo configuran, monitorizan, alojan e implementan los administradores de TI el producto de software para los usuarios? Este tipo de documentación es importante, especialmente cuando se añaden múltiples versiones o ramas.

En cierto modo, la documentación de producto es como enseñar a alguien a conducir un coche. El volante gira el coche, el acelerador mueve el coche, el freno detiene el coche. La documentación de software enseña cómo funciona el coche. El volante está conectado al eje delantero que gira las ruedas delanteras para alterar la dirección; el acelerador aumenta el flujo de aire al motor que atrae más combustible, generando par y potencia.

Ambos tipos de documentación son importantes. Uno educa a los usuarios y otro a los administradores y desarrolladores. Es genial mostrar a las personas cómo conducir un coche, pero si nadie sabe cómo funciona, ¿qué pasa cuando se avería?

Pequeñas diferencias entre la documentación de producto y software¶

Existen algunas diferencias a tener en cuenta entre la documentación de producto y software:

Documentación de software y producto: público objetivo y persona¶

La documentación de producto atiende a un solo público: el usuario. Asume que el usuario no tiene conocimientos técnicos, comunicándose en lenguaje sencillo con mínima jerga. Similar a un aprendizaje técnico frente a una carrera universitaria, enseña a las personas cómo hacer cosas, con menos énfasis en conocimientos teóricos o conceptuales.

La documentación de software está dirigida a administradores de TI, ingenieros y desarrolladores. Abarca el diseño y arquitectura del software, instrucciones de configuración por línea de comandos, soporte de API e integraciones, gestión de datos e informes, topología de red – básicamente los engranajes que hacen funcionar la máquina. Estos documentos forman una única fuente de verdad (SSOT) a la que el personal de TI puede referirse al supervisar y solucionar problemas de la aplicación.

Documentación de software y producto: frecuencia de actualizaciones¶

La documentación de software debe actualizarse constantemente a medida que se integran nuevos cambios en el canal principal de lanzamiento. Esta documentación debe destacar nuevas funciones y comandos, y deprecar características antiguas. Se deben documentar las dependencias nuevas o cambiantes, y aclarar el soporte de características en todas las plataformas objetivo – como una función que funciona en Windows, pero no en Linux.

La documentación de producto solo necesita actualizarse cuando los cambios en el software provocan un cambio en el flujo de trabajo o la usabilidad. Un desarrollador cambia el código de una pasarela de pago, pero el proceso de pago para los usuarios sigue siendo el mismo, por lo que no se necesitan actualizaciones.

Esto muestra una jerarquía natural para la documentación de productos de software. La documentación técnica forma la base, y la documentación de producto subsiguiente se basa en este fundamento. Por tanto, el enfoque debería estar en crear una excelente documentación de software, ya que genera una documentación de producto aún mejor.

Ejemplos de marcos de formato para documentación de producto y software¶

Un documento de producto podría seguir este marco:

• Nombre del producto
• Descripción general del propósito
• Guía de configuración
• Explicación e imágenes de la característica 1
• Explicación e imágenes de la característica 2
• Enlaces de soporte al cliente

De manera similar, un documento de software podría seguir este marco:

• Nombre del software
• Descripción general del propósito
• Dependencias del software
• Guía de instalación
• Explicación e imágenes de la función 1
• Explicación e imágenes de la función 2
• Enlaces de soporte técnico

Claramente, estos dos tipos de documentación están estrechamente relacionados y siguen una estructura similar. Esto significa que los equipos de producto y software tienen mucho que aprender unos de otros, y mucho potencial cuando trabajan en colaboración en la documentación.

Los equipos de documentación de producto y software pueden complementarse¶

Existen marcadas similitudes entre la documentación de producto y software. Esto plantea la pregunta: ¿pueden los equipos de producto y software trabajar juntos?

¡Sí, pueden y deberían hacerlo!

Los equipos de software entienden la jerga técnica y las tecnologías subyacentes. Los equipos de producto entienden lo que los usuarios ven, quieren y necesitan; la experiencia del usuario. Los redactores de documentación de software pueden proporcionar información técnica detallada, y los redactores de documentación de producto pueden simplificar los detalles técnicos para el consumo de un público no especializado.

Imagina tratar de explicar algo en términos sencillos, sin tener la comprensión de alto nivel necesaria para formular algo que un profano entendería. Eso es lo que sucede cuando la documentación de producto se crea antes que la documentación de software.

¿Qué es la mecánica cuántica? ¡El gato de Schrödinger es probablemente lo primero que viene a tu mente! Pero, ¿qué tiene que ver la mecánica cuántica con los gatos? Para el usuario, no es importante. Para un físico, lo significa todo.

Comienza con documentación de software, termina con mejor documentación de producto en Docsie¶

En conclusión, hay muchos beneficios al usar la documentación de software como plantilla para la documentación de producto posterior. La documentación de software debe actuar como fuente única de verdad para el personal de TI y los redactores de documentación de producto. Después de escribirla, los redactores de documentación de producto tendrán la claridad y comprensión para simplificar y compartir conocimientos fáciles de usar con los clientes, con orientación técnica para la revisión y control de calidad.

Simplemente, ¡comenzando con una excelente documentación de software, tus redactores pueden crear una documentación de producto aún mejor!

Comienza a crear documentación que ayude a tus clientes a hacer más. Regístrate en nuestro plan Startup (¡gratis para siempre!) y ofrece una experiencia de documentación excepcional con Docsie.