¿Qué plataformas usar para escribir documentación/ayuda/manual?

Llegué a un punto en el que es absolutamente necesario tener algún tipo de documentación sobre mi producto. Entonces, algún tipo de ayuda o manual de usuario para los clientes, porque quiero reducir la cantidad de correos electrónicos.

Así que estaba buscando algo que me permita:

  • exportar a PDF

  • maneja las traducciones (¿posiblemente dando acceso limitado a los traductores?)

  • implementación en línea, en mi página web/servidor, ...

  • (no es una condición) integrable en wordpress

Algo así como Manula por ejemplo. Manula no es gratis, lo que no es un problema, pero es bastante caro, lo que representa un pequeño problema. ¿Hay algo similar y tal vez algo que recomendarías?

¿Que usas?

¿Podría especificar de alguna manera la calidad prevista de los respectivos formatos de documentos emitidos, por favor? Algo que se lee bien en la pantalla (con enlaces internos, etc.) a menudo se puede convertir a PDF de alguna manera , pero el documento resultante generalmente se ve como lo que es, básicamente una página web forzada en papel impreso. Por el contrario, los documentos PDF bien diseñados y estructurados a menudo resultan difíciles de manejar cuando su contenido y estructura se transfieren directamente a algo como HTML. (Estoy pensando en mis experiencias con DocBook y algunos otros generadores multiformato aquí).
@ORMapper Gracias por señalarlo. Es una pena que realmente no haya pensado en eso. Idealmente, me gustaría tener algo que se pueda leer bien en la pantalla y, al mismo tiempo, esté bien diseñado en un documento PDF. Supongo que esa no es una opción. Si tengo que decidir, prefiero tener cosas bien legibles y fáciles de usar en la pantalla a costa de un diseño ligeramente más débil de un documento PDF.
Lo bueno de Sphinx es que, dado que cada tipo de documento se genera en lugar de convertirse, es posible tener varios formatos bien diseñados de una sola fuente: @Mawg tiene un punto, por lo tanto, RTFM, pero no puede RTFM cuando no hay manual

Respuestas (3)

Personalmente, puedo recomendar Sphinx Document Generator :

  • Gratis, gratis y de código abierto
  • plataforma cruzada
  • Un conjunto de archivos base, en formato ReStructuredText , cuya versión se puede controlar fácilmente.
  • Inclusión simple de capturas de pantalla, etc.
  • Formatos de salida: HTML (incluida la Ayuda HTML de Windows), LaTeX (para versiones PDF imprimibles ), ePub, Texinfo, páginas de manual, texto sin formato.
  • Mecanismos para la internacionalización donde se traducen las palabras y frases del texto en lugar de todo el documento.
  • Múltiples estilos
  • Generación automática de Tabla de Contenidos, Índice, Referencias Cruzadas, Glosario, Citas, etc.
  • Resaltado de sintaxis extensible y en varios idiomas
  • Utilizado por 100s de proyectos para una gran base de usuarios y mucho soporte.

Notas sobre la internacionalización

Para ampliar la internacionalización, a menudo llamada I18N porque requiere mucho menos tipeo, Sphinx usa el mismo sistema probado que la mayoría de los proyectos de código abierto han usado desde que se lanzó gettext en 1995.

Utiliza una herramienta de generador de catálogos de mensajes dentro de Sphinx para producir un conjunto de archivospot que son catálogos de mensajes, plantillas de objetos estrictamente portátiles , que contienen palabras, frases y párrafos de su documento original. Copias de estos se envían a los traductores para los idiomas deseados que utilizan una herramienta como Pootle o poedit para proporcionar sus traducciones individuales y devolverlas como objetos portátiles ,.po archivos. Tenga en cuenta que todo esto se puede hacer de forma colaborativa utilizando servicios como Transfex .

Estos .poarchivos se ejecutan a través de la herramienta gettext msgfmt para producir objetos de mensaje, .moarchivos. Una vez que se hayan agregado a su proyecto, en una ubicación específica del idioma, puede ejecutar Sphinx nuevamente especificando el idioma de salida y sus documentos se imprimirán en el idioma solicitado. Cualquier traducción faltante permanecerá como el texto original.

Una de las grandes ventajas de este enfoque es que si realiza cambios en sus documentos, como sucede inevitablemente, la cadena de herramientas muestra a los traductores lo que ya está traducido y solo tienen que actualizar los elementos nuevos/modificados y cualquier elemento incorrecto. . Otra es que nunca tendrá que mantener varias copias de su documento de origen (por lo general, esto termina siendo una por idioma), solo de sus archivos de traducción.

Flujo de trabajo de traducción de Sphinx

Cortesía de flujo de trabajo del sitio web Sphinx , figura de palo originalmente del cómic XKCD

Diagramas y Gráficos

Si su documentación incluye diagramas con texto, puede usar una de varias extensiones de Sphinx , como las extensiones de Graphviz para generar los diagramas automáticamente, en el caso de Graphviz usando el lenguaje de puntos , o puede generar diagramas y gráficos incrustando algo de python. en su documento, lo que permitirá que sus diagramas y gráficos se actualicen automáticamente al momento de crear su documento, incluso puede superponer texto en imágenes y fotografías de esta manera. Lo bueno de esto es que está incrustando algún texto que produce el gráfico, etc., en lugar de incrustarlos directamente, lo que es mejor tanto para el control de versiones como para la internacionalización. También hay extensiones para Google Charts & Maps

¿Sabes algo sobre la GUI de Sphinx? Mi pregunta es: si dejo a los traductores en las páginas de administración: ¿sabrán qué hacer o necesitan al menos conocimientos básicos de programación? ¿Tienes alguna experiencia en eso?
@skrat No tiene que dar a los traductores ningún acceso de cambio y no necesitan experiencia en programación. He ampliado mi respuesta para dar mi comprensión del proceso.
@skrat También puede usar las mismas herramientas básicas y flujo de trabajo en su código para internacionalizar su software, básicamente etiqueta cadenas en su lugar, se extraen al archivo pot, etc. pero las etiquetas también son macros para llamadas a traducir que seleccionarán actualice las traducciones del .mo para el idioma actual, si está presente. Esto incluso le permite, una vez que tenga su primera traducción funcionando, agregar idiomas sin reconstruir su código, consulte gnu.org/software/gettext/manual/html_node/… para idiomas.

El "escritor" de Libre Office le permitirá generar tanto en HTML como en PDF.

Cuando llegue el momento, puede preparar fácilmente sus documentos para la Web a través de la función de exportación HTML de Writer, o puede publicarlos automáticamente en un wiki en formato MediaWiki.

Si necesita estar seguro de que lo que publica se puede ver y se ve exactamente en cada tipo de dispositivo y plataforma de lectura, la función "Exportar como PDF" (.pdf) genera un archivo .pdf. La función de exportación de PDF de LibreOffice proporciona una gran cantidad de opciones de formato y seguridad, lo que le permite satisfacer muchas restricciones diferentes, incluida la producción de archivos PDF/A con estándar ISO.

Ok, pero ¿cómo harías la documentación/ayuda multilingüe con libre?

Últimamente he visto que Read the Docs se usa en muchos proyectos (SO). Por lo que puedo decir, está dirigido principalmente a la documentación del código, no estoy seguro de si eso se ajusta a sus necesidades.

Lea la documentación de los anfitriones de Docs, lo que la hace totalmente fácil de buscar y fácil de encontrar. Puede importar sus documentos utilizando cualquier sistema de control de versiones principal, incluidos Mercurial, Git, Subversion y Bazaar. Admitimos webhooks para que tus documentos se construyan cuando confirmas el código. También hay soporte para el control de versiones para que pueda crear documentos a partir de etiquetas y ramas de su código en su repositorio.

Read the Docs usa Sphinx como su back-end principal y recomienda reStructuredText como su formato de envío. Consulte read-the-docs.readthedocs.io/en/latest/getting_started.html
¿Qué plataformas usar para escribir documentación/ayuda/manual?
RespuestasAquíPolítica de privacidad1y, 0v