¿Qué herramientas utiliza su equipo para escribir manuales de usuario? [cerrado]

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

Pregunta

Las solicitudes básicas son:

  • formato de texto / legible para humanos (para un control sencillo de la versión)
  • en línea (para colaboración)
  • formato fácil (rebaja ok, html es demasiado)
  • formato estricto (para que los autores no inventen nuevos tipos de títulos, viñetas, etc.)
  • exportable a PDF, HTML
  • copia de seguridad e implementación fáciles (para que podamos "implementar" en el sitio de los clientes como versión de solo lectura)

Estamos pensando en usar algún tipo de motor wiki, pero necesitaría usar archivos para el almacenamiento o tener otros medios de "implementación". al cliente y sea fácil de instalar / mantener. Además, tendría que ser gratuito / barato (la confluencia es demasiado costosa)

¿Alguna sugerencia?

Editar: no estoy buscando herramientas para documentar código, lo hemos cubierto usando Sandcastle.

¿Fue útil?

Solución

Aunque puede que no responda a todas sus solicitudes, puede valer la pena echar un vistazo a DokuWiki .

Al igual que con otros wikis, tiene una sintaxis simple , y tiene control de versión para realiza un seguimiento de las revisiones , genera tabla de contenido y una función búsqueda de texto completo que puede ser útil para un sistema de ayuda .

Es posible que desee evaluar la lista de funciones para ver si satisface sus necesidades.

Además, parece que también hay una buena colección de complementos disponibles . Aunque no he usado DokuWiki o sus complementos, parece que hay complementos disponibles para exportación de PDF también.

Otros consejos

Para nuestra API, utilizamos Doxygen , lo cual es genial.

Pandoc es una herramienta fantástica para convertir entre varios formatos de marcado. Escribimos documentos en Markdown y usamos Pandoc para convertir a otros formatos.

Desde el sitio de pandoc:

  

Si necesita convertir archivos de uno   formato de marcado en otro, pandoc es   tu navaja suiza Pandoc puede leer Markdown y   (subconjuntos de) reStructuredText,   textil, HTML y LaTeX, y puede   escribir texto plano, rebajas,   reStructuredText, HTML, LaTeX,   ConTeXt, PDF, RTF, DocBook XML,   OpenDocument XML, ODT, GNU Texinfo,   MediaWiki marcado, textil, hombre groff   páginas, Emacs org-mode, EPUB ebooks,   y presentaciones de diapositivas S5 y Slidy HTML. PDF   salida (a través de LaTeX) también es compatible   con el contenedor incluido markdown2pdf   guión.

Pandoc obtiene puntos extra por ser de código abierto y escrito en el calor que es Haskell;)

No puedo decir lo suficiente sobre Asciidoc . Tiene una sintaxis de marcado muy simple, puede generar todo, desde pdf a roff, portátil para implementar e insertar fácilmente en cualquier wiki con solo unos pocos cambios menores.

Incluso en su estado de marcado, es muy, muy fácil de leer. Lo único con lo que tengo que jugar cuando lo uso son las tablas, pero eso no es demasiado difícil.

Si mantiene los archivos con formato de texto en su repositorio, el seguimiento de revisiones es bastante simple.

Para la documentación del código, uso doxygen .

Utilizamos ayuda y manual para el manual y el archivo de ayuda. No hay exportación html, pero proporciona ayuda html, winhelp, pdf y algunos formatos más.

Estamos usando una wiki. Recomiendo MoinMoin porque

  • muy simple de configurar (incluso en una computadora portátil)
  • muy simple para hacer una copia de seguridad (incluso puede enviar el wiki a un sistema de control de versiones para sincronizarlo, por ejemplo, con computadoras portátiles para uso sin conexión).
  • buena sintaxis
  • fácil de extender
  • Fácil de buscar

No estamos usando algo como Word porque:

  • La documentación se pudre demasiado rápido
  • Buscar en todos los documentos es una molestia
  • Vincular entre bits de información es un dolor
  • Sin diferencias entre versiones
  • Formato binario que elimina cualquier VCS
  • Sin marcadores profundos
  • Los documentos crecen demasiado y luego se vuelven torpes: dividir (y no buscar más) o esperar años para cargar.

No menciona el lenguaje / marco que está utilizando. Existen herramientas de documentación realmente buenas, pero algunas de ellas son específicas de lo que está desarrollando. Somos una tienda de C #, por lo que mi respuesta solo se aplicará a usted si está utilizando .NET.

Utilizamos Sandcastle , que no solo es gratuito, sino de código abierto. Si bien la gente lo considera principalmente como una aplicación estrictamente que genera documentación a partir de documentación XML, puede proporcionar su propio contenido en MAML. Puede dirigirse tanto a CHM como a implementaciones de sitios web, lo que satisface nuestras necesidades. Hay algunas herramientas adicionales que pueden proporcionar cosas como marcar favoritos y clasificaciones de temas a mi entender, pero aún no hemos comenzado a usarlas.

Esto nos proporciona documentación interna y externa. Dado que también usamos Team Foundation Server, utilizamos el Wiki incorporado en Team Project en Sharepoint, pero eso está más orientado a la colaboración del proyecto.

Editar: se corrigió el enlace roto, y también quería mencionar que hay otras herramientas en conjunto con Sandcastle, que utilizamos. Cosas como Sandcastle Help File Builder y GhostDoc son herramientas comunes. El primero en editar los proyectos Sandcastle y MAML, y el segundo en mejorar la calidad de los comentarios en el código.

Pruebe Sphinx . Toda la documentación de Python se realiza con esta herramienta http://docs.python.org/

Para " manuales " ;, Docbook. Es un dialecto SGML diseñado para documentación técnica. http://www.docbook.org/ . Es posible que no cumpla con su "marcado fácil" criterio, pero definitivamente produce una buena salida en LaTex (se puede convertir luego a PDF) y una buena salida HTML si cocina su propia hoja de estilo CSS. Los archivos de texto se mantienen en el control de versiones. Todos los programas también usan una biblioteca que combina el análisis de argumentos de línea de comandos con " - help " salida en una variedad de formatos (normal, página man y docbook). Para la referencia API, doxygen, por supuesto.

En mi trabajo actual producimos software de un solo uso, por lo que la documentación a menudo se pone al margen y se realiza en Word.

Sin embargo, en mi último trabajo, el equipo de documentación parecía enloquecer y hablar sobre Producto del software de Mad Cap " Flare " . Le permite escribir en un formato y publicar en muchos medios, por lo que su manual también puede ser su ayuda en línea o un sitio web, etc.

pruebe Dikiwiki

Usamos Word. Se pone en nuestro control de versiones, por lo que tenemos historial (hay una carpeta de documentación vinculada a cada proyecto). El formateo se puede controlar usando plantillas, que ahora hemos configurado, por lo que hacer cambios es fácil de hacer dentro de los estándares de diseño. Los archivos se pueden exportar a PDF. Puede publicarlos como documentos de solo lectura para compartir con los usuarios.

Hemos tenido un gran éxito con DocToHelp . Funciona muy bien con la documentación basada en Microsoft Word, así como con otros formularios, e incluso tiene algunas excelentes características de integración para Visual Studio.

La mejor parte es que una vez que haya importado una base de documentos centrales a DocToHelp, puede elegir cualquiera de los diversos formatos de exportación, ya sea WinHelp, Ayuda HTML, Ayuda Java o la Ayuda de red agradable y sofisticada.

Para documentar el código utilizo Doxygen. Prefiero la versión de Linux, tuve problemas con algunas características en la versión de Windows

Mi compañía usa MediaWiki y TikiWiki para la mayoría de la documentación. También tenemos un tipo que compila cosas en formatos MS Word y PDF para imprimir / enviar a los clientes. Te recomiendo que evites TikiWiki como la peste. MediaWiki es genial, tanto porque es realmente fácil de usar como porque todos saben cómo usarlo: es el wiki estándar de facto y, en mi opinión,

Durante algún tiempo estuvimos usando DocBook, pero fue muy difícil ampliarlo con funciones más avanzadas y necesarias (resaltado de sintaxis, división en varios archivos, gestión de multilingüismo, etc.). Más tarde, decidimos escribir nuestro propio sistema desde cero y publicarlo como código abierto: texto del enlace . Utiliza archivos de texto sin formato y Markdown como lenguaje de sintaxis, y ahora tenemos todo lo que necesitamos. La desventaja es que actualmente no hay probablemente un analizador Markdown que produzca algo más que la salida HTML. Por ahora esto es suficiente, pero estamos pensando en implementar la compatibilidad con PDF muy pronto.

Además, mantenemos MediaWiki como una ayuda basada en la comunidad.

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