version control - tutorial - Qué es una buena herramienta para escribir un manual de usuario(archivo de ayuda), que se integra con el control de versión
Las personas que escriben el manual de usuario no son necesariamente programadores, y necesitan un editor visual. Un problema importante es el formato interno de la herramienta de autoría; debe ser legible text / html, por lo que es fácil comparar versiones de páginas individuales registradas en el control de la versión.
El Taller de ayuda de Microsoft HTML se puede utilizar para crear archivos profesionales de ayuda de CHM de buena calidad. Todo lo que necesitas es un montón de archivos HTML. La herramienta "compila" todos estos y paquetes en un solo archivo de Ayuda. Los archivos HTML se pueden generar usando Microsoft Word / Frontpage o incluso Dreamweaver. Es posible que desee considerar la fuente que controla estos archivos HTML.
Estamos usando APT . Se integra bien con el IC (artefacto de construcción estándar) y está más vivo que, por ejemplo, el documento de Word. También es posible generar archivos PDF y otros formatos cuando sea necesario.
Existen otros productos profesionales que permiten la escritura de archivos de ayuda y tienen soporte de "ID de contexto" que hace posible la ayuda contextual. Doc To Help y RoboHelp son este tipo de productos.
Puede usar Subversion y MGTEK Help Producer. Help Producer crea archivos de ayuda a partir de documentos de Word. TortoiseSVN viene con scripts para comparar diferentes revisiones de documentos de Word, en Word en sí (Word tiene una herramienta de comparación de versiones).
Sus usuarios van a querer una herramienta visual diff que se asemeje a la que están editando. Si simplemente no son un poco técnicos, DocBook o Latex no van a funcionar (he intentado darles a ambos usuarios, e incluso intenté Epic Editor como un editor de DocBook que es muy costoso pero no funcionó muy bien después de todo). Mantener algo que saben (Word) evitará muchos dolores de cabeza.
Yo también era muy reacio a tomar esta ruta al principio, porque quería una solución que fuera más "técnicamente perfecta", pero me di cuenta con el tiempo de que tener usuarios felices y productivos era más importante. Simplemente digo que sé de dónde vienes, pero prueba la ruta de Word; funciona mucho mejor en la práctica que todas las soluciones basadas en texto "puras" que existen. A los usuarios regulares no les gusta la edición basada en marcado.
Si está usando Visual Studio, eche un vistazo a SandCastle - http://www.codeplex.com/Sandcastle .
También hay un par de herramientas que te ayudan a construir archivos de castillo de arena, intenta buscar "castillo de arena" en codeplex. Uno de ellos es SandCastle Help File Builder ( http://www.codeplex.com/SHFB ), pero nunca lo he usado, así que no sé si los usuarios no técnicos estarán contentos con eso.
Mapcap Flare es la mejor herramienta comercial disponible. Escrito por los ex desarrolladores de Robodoc
Una buena combinación para considerar es Subversion, DocBook y Publican.
- Control de versiones = Subversion
- Autoría de contenido = DocBook
- Publicación = Publican
- WYSIWYG opcional = Serna
Por el momento, esta es una de las cadenas de herramientas en uso por el mayor proveedor del mundo de soluciones de código abierto, y el nombre detrás de gran parte del uso mundial de los sistemas operativos basados en Linux en el mercado empresarial. La mayoría (y casi todos) de la documentación oficial de Red Hat se crea de esa manera. Lo mismo ocurre con Fedora.
El principal "pro" aquí es que estas son herramientas disponibles libremente, con una fuerte superposición en el mercado de escritores técnicos. Todos ellos podrán (aunque no quieran) escribir en XML, y recoger DocBook es como recoger HTML en los años 90. Subversion es una herramienta de control de versiones muy común, que al igual que DocBook es relativamente fácil de implementar y usar. Publican es una gran herramienta de publicación que puede tomar DocBook XML y publicarlo en PDF, HTML, HTML-single, etc. Obviamente, sus escritores pueden usar un WYSIWYG como Serna, pero yo uso fragmentos en Geany (en Fedora) o TextMate (en OS X) personalmente.
La principal "estafa" es la percepción del tecnicismo. Sus escritores pueden querer WYSIWYG (y pueden tenerlo), y dependiendo de sus necesidades de documentación, esto podría ser lo que termine usando. Como sabría, existe un mercado para los "Escritores Técnicos" que se especializan en corregir estilos (y marcas) de Microsoft Word, por lo que los argumentos para separar "creación" de "publicación" se basan en casos de uso probados pero distintos para organizaciones que requieren que la documentación se mantenga hasta con los mismos estándares de la ingeniería / programación / fuente de producción.
Algunos de los consejos extremos que obtendrá provienen de personas y compañías que han estado expuestas al valor de la documentación XML, y especialmente aquellas en los dominios de DITA, donde ciertas multinacionales tienen una reputación de adquisiciones que están influenciadas por el formato y disponibilidad del conocimiento del producto. También existen argumentos que indican que bloquear su documentación en un formato "cerrado" o cerrado no ayuda a los requisitos de mantenimiento futuros. Aquí es donde las opciones de código abierto obtienen soporte a nivel corporativo. Además, obviamente, es gratis.
En mi antiguo trabajo, usaron una herramienta de un programa alocado llamado Flare .
Parecía funcionar realmente bien.
Creé un sistema de documentación llamado Mandown ( Markdown / Html / Javascript / documentos relativamente vinculados basados en archivos para la portabilidad) que fácilmente pasaría a estar bajo control de versiones. La parte del editor visual debería interpretarse por separado: a veces uso HTML-Kit, que al menos tiene una función de vista previa.
Consulte ¿Cuál es la mejor manera de almacenar la documentación del software?
Aquí hay otra herramienta para ver: Xilize