Tanto los equipos de producto como los de software tienen un enemigo común: la documentación.
La documentación del producto se refiere a los manuales y guías para el usuario que explican el flujo de trabajo y la interfaz de usuario de un producto. ¿Cómo puede el usuario medio ser productivo con este producto? En este sentido, la documentación del producto podría utilizarse para los productos de software.
La documentación de software se refiere a las tecnologías subyacentes, los requisitos previos y los atributos configurables de un producto de software. ¿Cómo configuran, supervisan, alojan y despliegan 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 a la mezcla.
En cierto sentido, la documentación del producto es como enseñar a alguien a conducir un coche. El volante hace girar el coche, el pedal del acelerador lo mueve y el pedal del freno lo detiene. La documentación del software enseña a alguien cómo funciona el coche. La rueda está conectada al eje delantero, que hace girar los neumáticos delanteros para modificar la trayectoria; el acelerador aumenta el flujo de aire hacia el motor, que aspira más combustible, generando par y potencia.
Ambos tipos de documentación son importantes. Una educa a los usuarios y la otra a los administradores y desarrolladores. Está muy bien enseñar a conducir un coche, pero si nadie sabe cómo funciona, ¿qué pasará cuando se averíe?
Pequeñas diferencias entre la documentación del producto y la del software
Existen pequeñas diferencias entre la documentación de productos y la de programas informáticos:
Documentación de software y de producto: Público objetivo y Persona
La documentación de producto se dirige a un único público: el usuario. Asume que el usuario no tiene conocimientos técnicos y se comunica en un inglés sencillo con un mínimo de jerga. Al igual que un aprendizaje técnico frente a un título universitario, educa a las personas sobre cómo hacer las cosas, centrándose menos en los conocimientos teóricos o conceptuales.
La documentación de software se dirige a administradores, ingenieros y desarrolladores de TI. Abarca el diseño y la arquitectura del software, instrucciones de configuración de la línea de comandos, API y soporte de integración, gestión de datos e informes, topología de red... básicamente, los engranajes que hacen funcionar la máquina. Estos documentos constituyen una única fuente de información (SSOT) a la que el personal informático puede remitirse para supervisar y solucionar problemas de la aplicación de software.
Documentación de software y productos: Frecuencias de actualización
La documentación del software debe actualizarse sistemáticamente a medida que se incorporan nuevos commits al canal de publicación principal. La documentación del software debe destacar las nuevas funciones y comandos, y dejar obsoletas las características antiguas. Deben documentarse las dependencias nuevas o cambiantes, y debe aclararse la compatibilidad de las funciones con todas las plataformas de destino (por ejemplo, si una función funciona en Windows, pero no en Linux).
La documentación del producto sólo debe actualizarse cuando las modificaciones del software subyacente provoquen 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 es necesario actualizarlo.
Esto muestra una jerarquía natural para la documentación de productos de software. La documentación técnica del software constituye la base sobre la que se asienta la documentación posterior del producto. Por lo tanto, la atención debe centrarse en hacer una gran documentación de software, ya que genera una documentación de producto aún mayor.
Ejemplos de marcos de formato para la documentación de productos y software
La documentación de un producto podría seguir este esquema:
-
Nombre del producto
-
Descripción de la finalidad del producto
-
Guía de instalación
Explicación e imágenes de la Característica 1.
-
Explicación e imágenes de la función 2
-
Enlaces de atención al cliente
Del mismo modo, la documentación de un programa informático podría seguir este esquema:
Nombre del software
-
Descripción de la finalidad del software
-
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 asistencia técnica
Está claro que estos dos tipos de documentación están estrechamente relacionados entre sí y siguen una estructura similar. Esto significa que los equipos de producto y software tienen mucho que aprender los unos de los otros, y mucho potencial cuando trabajan en colaboración en la documentación.
Los equipos de documentación de productos y software pueden complementarse
Existen grandes similitudes entre la documentación de productos y la de software. Esto plantea la siguiente pregunta: ¿pueden trabajar juntos los equipos de producto y software?
Sí, pueden y deben 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 diluir los detalles técnicos para que los consuma un público no especializado.
Imagínese tratar de explicar algo en términos sencillos, sin tener los conocimientos de alto nivel necesarios para formular algo que un profano pueda entender. Eso es lo que ocurre cuando la documentación del producto se crea antes que la documentación del software.
¿Qué es la mecánica cuántica? Seguro que lo primero que se le viene a la cabeza es el gato de Schrodinger. Pero, ¿qué tiene que ver la mecánica cuántica con los gatos? Para el usuario, no tiene importancia. Para un físico, lo es todo.
Comience con la documentación del software, termine con una mejor documentación del producto en Docsie
En conclusión, el uso de la documentación del software como plantilla para la posterior documentación del producto tiene muchas ventajas. La documentación del software debe actuar como una única fuente de verdad para el personal de TI y los redactores de la documentación del producto. Una vez redactada, los redactores de la documentación del producto dispondrán de la claridad y la comprensión necesarias para simplificar y compartir con los clientes conocimientos fáciles de utilizar, con orientación técnica para la corrección de pruebas y el control de calidad.
Sencillamente, si empieza con una buena documentación de software, sus redactores podrán elaborar una documentación de producto aún mejor.
Empiece a crear documentación que ayude a sus clientes a hacer más. ¡Suscríbase a nuestro plan Startup (forever free!) y ¡ofrezca una documentación excelente con Docsie!