¿Qué herramientas se pueden usar para construir la documentación del usuario final de manera eficiente?

¿Cómo se define la eficiencia? Algunas compañías dicen “Oh, necesitamos documentación, pero a los desarrolladores no les gusta escribirla y otras tampoco están contentas de hacerlo”. Para esas compañías, la eficiencia a menudo equivale a “Nos gustaría que los documentos existan en forma mínima sin gastar demasiados recursos en ello y sin contratar a un escritor técnico “.

En mi respuesta, no cubriré el ejemplo anterior. Prefiero hablar sobre una situación diferente: “Nos gustaría construir un proceso alrededor de la creación de documentación para el usuario final. Tiene que ser eficiente en términos de gestión de procesos y utilización de recursos; no queremos perder tiempo en algo que pueda automatizarse o hacerse de una mejor manera ”. Este es el tipo de “eficiencia” de la que me gustaría hablar. En este sentido, puede ver estos elementos como requisitos:

1. Mínimos esfuerzos de instalación y mantenimiento.
   Las soluciones en la nube resolverán esto por usted: herramientas como ClickHelp no requieren instalación, mantenimiento o actualizaciones. Usted se registra y pone en marcha su entorno completo en minutos.
2. Flujo de trabajo de documentos fácil para autoría y revisión.
   Cuando más de una persona contribuye (como autor, revisor, PYME, editor, etc.), no puede permitirse el uso de correo electrónico y archivos compartidos para intercambiar documentos actualizados. Esos procesos antiguos tienen un alto riesgo de perder los últimos cambios, la falta de correos electrónicos y la publicación de un documento no listo. Por lo tanto, recomiendo buscar una herramienta que tenga un flujo de trabajo de documentos conveniente y flexible que se adapte a sus necesidades.
3. Formatos en línea como entregables.
   La gente está buscando respuestas en Internet, por lo que no poner sus documentos en línea es simplemente … no muy inteligente en muchos sentidos. Por lo tanto, necesita una herramienta que produzca una buena documentación en línea. Es posible que necesite o no formatos impresos del mismo contenido, por lo que esta parte depende de usted al elegir la herramienta s.
4. Proceso de actualización de documentación simple.
   Vas a construir un proceso, y no solo una versión única del documento que saldrá para siempre, ¿verdad? Por lo tanto, deberá actualizar los documentos con bastante frecuencia para mantenerlos actualizados, agregar más información en función de las solicitudes de soporte técnico, etc. Si crea sus documentos en el formulario HTML y luego debe ir a Administradores y Equipo web cada cada vez que necesite cargar una nueva versión en su servidor web, esto agregará otro cuello de botella a su proceso y extenderá el tiempo para actualizar los documentos. Para evitar esto, puede preferir una solución de portal de documentación en línea integrada que le brinde tanto el entorno de autoría como el de alojamiento con una manera fácil de actualizar las guías del usuario.

Entonces, esas son solo cuatro cosas que me vienen a la mente sobre la eficiencia del proceso de documentación. Con todas esas cosas en mente, es posible que desee buscar una solución de portal de documentación en la nube como ClickHelp y probarla para ver cómo funciona según sus requisitos.

¡Buena suerte con tus esfuerzos de documentación!

Depende de la naturaleza del proyecto y la pila de tecnología detrás de él.
En general:

• Prefiere las herramientas basadas en el formato de texto (markdown / wiki) a los formatos binarios (PDF, DOC, CHF). Es más fácil comparar revisiones.
• La herramienta debe ser capaz de hacer accesible la documentación a través del navegador (generar HTML / PDF).

Mi preferencia por tales herramientas va a Redmine (Descripción general – Redmine) y XWiki (XWiki – Wiki de aplicaciones y empresas de código abierto avanzado).

Avanzado: puede intentar generar partes de la documentación a partir del código fuente (consulte Javadoc) o los propios requisitos.

Lo mejor del flujo de trabajo de documentación es que hay una gran variedad de herramientas que le permiten armar una opción personalizada. Es divertido aprender cómo funcionan estos flujos de trabajo y porque las herramientas son interesantes y siempre están cambiando.

Para las empresas (especialmente las pequeñas empresas tecnológicas y las nuevas empresas), esto no es solo una pérdida de tiempo, sino a menudo una acumulación peligrosa de deuda técnica futura. Dado que hay empresas SaaS especializadas en flujos de trabajo de documentación: si pasa más de una hora al mes manteniendo una cadena de herramientas de documentación, está desperdiciando dinero.

He vivido este viaje como escritor técnico en Red Hat. Creamos una herramienta interna para nosotros, y me inspiró llevar esto a otro nivel y diseñar un flujo de trabajo basado en la colaboración del equipo.

Construimos Corilla como una herramienta de documentación colaborativa para equipos de software. Corilla resuelve el problema de escribir y administrar contenido en un flujo de trabajo, con un portal de documentación totalmente alojado, base de conocimiento, control de versiones y administración de imágenes. Estamos en uso en más de 85 países y enviamos actualizaciones semanalmente gracias a una comunidad altamente comprometida de ingenieros y diseñadores de contenido.

¡Me encantaría tu opinión!