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

Las personas que escriben el manual de usuario no son necesariamente progtwigdores, y necesitan un editor visual. Un problema importante es el formatting 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.

Existen otros productos profesionales que permiten la escritura de files de ayuda y tienen soporte de "ID de context" que hace posible la ayuda contextual. Doc To Help y RoboHelp son este tipo de productos.

El Taller de ayuda de Microsoft HTML se puede utilizar para crear files profesionales de ayuda de CHM de buena calidad. Todo lo que necesitas es un montón de files HTML. La herramienta "comstack" todos estos y packages en un solo file de Ayuda. Los files HTML se pueden generar usando Microsoft Word / Frontpage o incluso Dreamweaver. Es posible que desee considerar la fuente que controla estos files HTML.

Látex . Lyx proporciona WYSIWYM para escribir files de látex.

En mi antiguo trabajo, usaron una herramienta de un software alocado llamado Flare .

Parecía funcionar realmente bien.

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 documentation 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 superposition 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 fragments 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 documentation, esto podría ser lo que termine usando. Como sabrá, existe un mercado para los "Escritores Técnicos" que se especializan en corregir styles (y marcas) de Microsoft Word, por lo que los arguments para separar "creación" de "publicación" se basan en casos de uso probados pero distintos para organizaciones que requieren que la documentation se mantenga hasta con los mismos estándares de la ingeniería / progtwigció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 documentation XML, y especialmente aquellas en los dominios de DITA, donde ciertas multinacionales tienen una reputación de adquisiciones que están influenciadas por el formatting y disponibilidad del conocimiento del producto. También existen arguments que indican que bloquear su documentation en un formatting "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.

Puede usar Subversion y MGTEK Help Producer. Help Producer crea files 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 count con el time de que tener usuarios felices y productivos era más importante. Simplemente digo que sé de dónde vienes, pero testing la ruta de Word; funciona mucho mejor en la práctica que todas las soluciones basadas en text "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 build files de castillo de arena, intenta search "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

Creé un sistema de documentation llamado Mandown ( Markdown / Html / Javascript / documentos relativamente vinculados basados ​​en files 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 less tiene una function de vista previa.

Consulte ¿Cuál es la mejor manera de almacenar la documentation del software?


Aquí hay otra herramienta para ver: Xilize

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 files PDF y otros formattings cuando sea necesario.

    Intereting Posts