¿Qué es una buena herramienta para escribir un manual de usuario (archivo de ayuda), que se integra con el control de versiones [cerrado]?

StackOverflow https://stackoverflow.com/questions/152241

Pregunta

Las personas que escriben el manual del usuario no son necesariamente programadores, y necesitan un editor visual. Un problema importante es el formato interno de la herramienta de creación; debería ser texto / html legible, para que sea fácil comparar versiones de páginas individuales incluidas en el control de versiones.

¿Fue útil?

Solución

Hay otros productos profesionales que permiten la escritura de archivos de ayuda y son compatibles con " ID de contexto " lo que hace posible la ayuda sensible al contexto. Doc To Help y RoboHelp son este tipo de productos.

Otros consejos

DocBook

texto alt
(fuente: docbook.org )

Microsoft HTML Help Workshop puede utilizarse para crear archivos de ayuda de CHM profesionales 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 utilizando Microsoft Word / Frontpage o incluso Dreamweaver. Es posible que desee considerar la fuente que controla estos archivos HTML.

Latex . Lyx proporciona WYSIWYM para escribir archivos de látex.

En mi antiguo trabajo, utilizaron una herramienta del software madcap llamada flare .

Parecía funcionar muy bien.

Una buena combinación a considerar es Subversion, DocBook y Publican.

En este momento, esta es una de las cadenas de herramientas en uso por el proveedor más grande del mundo de soluciones de código abierto, y el nombre detrás de gran parte del uso mundial de 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 de libre acceso, con una fuerte superposición en el mercado de escritores técnicos. Todo lo cual podrá (pero no querrá) escribir en XML, y elegir 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 excelente 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 uso fragmentos de código en Geany (en Fedora) o TextMate (en OS X) personalmente.

El principal " con " Es la percepción del tecnicismo. Sus escritores pueden querer WYSIWYG (y pueden tenerlo), y según sus necesidades de documentación, esto podría ser lo que termine usando. Como sabría, hay un mercado para " Escritores técnicos " que se especializan en arreglar los estilos de Microsoft Word (y el marcado), por lo que los argumentos para separar " creación " de " publicación " se basan en casos de uso comprobados pero distintos para organizaciones que requieren que la documentación se mantenga según los mismos estándares de la ingeniería / programación / producción de fuente.

Algunos de los consejos extremos que recibirá provendrán de personas y compañías que han estado expuestas al valor de la documentación XML, y especialmente de aquellos en los ámbitos 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 los argumentos de que bloquear su documentación en un " adhesivo " o el formato cerrado no ayuda a los futuros requisitos de mantenimiento. Aquí es donde las opciones de código abierto obtienen soporte a nivel corporativo. Además, obviamente, es gratis.

Puedes usar Subversion y MGTEK Help Producer. Help Producer hace archivos de ayuda de documentos de Word. TortoiseSVN viene con scripts para comparar diferentes revisiones de documentos de Word, en el mismo Word (Word tiene una herramienta de comparación de versiones).

Sus usuarios van a querer una herramienta de visualización visual que se parezca a la que están editando. Si no son muy técnicos, el DocBook o el Latex no van a funcionar (he intentado darles a ambos usuarios, e incluso probé Epic Editor como un editor de DocBook que es muy costoso pero no funcionó muy bien después de todo. Mantenerte en algo que ellos saben (Word) te evitará muchos dolores de cabeza.

También me resistí mucho a ir por esta ruta al principio, porque quería una solución que fuera más "técnicamente perfecta", pero con el tiempo me di cuenta de que era más importante tener usuarios felices y productivos. Solo digo que sé de dónde viene, pero pruebe la ruta de Word: funciona mucho mejor en la práctica que todas las soluciones "puras" basadas en texto que existen. A los usuarios normales no les gusta la edición basada en marcado.

Si está utilizando Visual Studio, eche un vistazo a SandCastle - http://www.codeplex.com / Castillo de arena .

También hay un par de herramientas que te ayudan a construir archivos de castillos de arena, intenta buscar " sandcastle " 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.

Madcap Flare es la mejor herramienta comercial que existe. Escrito por los ex desarrolladores de Robodoc

Creé un sistema de documentación llamado Mandown ( Markdown / Html / Javascript / file-based documentos relativamente vinculados para la portabilidad) que se someterían fácilmente al control de versiones. La parte del editor visual que tendría que resolver 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 software? documentación?

Aquí hay otra herramienta para revisar: Xilize

Estamos utilizando APT . Se integra bien con el CI (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.

Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top