¿Qué herramientas usa su equipo para escribir manuales de usuario?

Question

peticiones básicas son:

• formato legible/texto (para facilitar el control de versiones)
• en línea (para la colaboración)
• formato fácil (reducción del precio bien, html es demasiado)
• formato estricto (lo que los autores no inventan nuevos tipos de títulos, balas etc.)
• exportables a PDF, HTML
• copia de seguridad y el despliegue fácil (por lo que podemos "desplegar" ac lientes sitio como leer única versión)

Estamos pensando en el uso de algún tipo de motor de wiki, pero tendría que usar archivos para su almacenamiento o tener otros medios de "despliegue" a los clientes y ser fácil de instalar/maintan. Además, debería ser gratis/barato (la confluencia es demasiado costosa)

¿Alguna sugerencia?

Editar: No estoy buscando herramientas para documentar el código, tenemos eso cubierto usando Sandcastle.

Answer 1

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

Al igual que con otros wiki, que tiene una simple syntax, y tiene el control de versiones a track revisions, genera table of contents, y una característica full-text search que puede venir a mano para un sistema de ayuda.

Es posible que desee evaluar el feature list para ver si se ajusta a sus necesidades.

Además, parece que también hay un buen collection of avaialble plugins. Aunque no he usado DokuWiki o sus complementos, parece que también hay complementos disponibles para PDF export.

Answer 2

Usamos help and 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.

Answer 3

tratar Dikiwiki

Answer 4

Utilizamos la palabra. 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 mediante plantillas, todas las cuales ahora hemos configurado, por lo que es fácil realizar cambios 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.

Answer 5

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

Answer 6

Estamos usando una wiki. Recomiendo MoinMoin porque

• muy simple de instalar (incluso en un ordenador portátil)
• muy simple de copia de seguridad (incluso se puede cometer el wiki para un sistema de control de versiones para sincronizarlo entre, por ejemplo, ordenadores portátiles para uso sin conexión)
• agradable sintaxis
• fácil de extender
• fácil buscar

No estamos usando algo como Palabra porque:

• Documentación pudre muy rápido
• Buscando todos los documentos es un dolor
• La vinculación entre bits de información es un dolor
• Sin diff entre las versiones
• formato binario, que caga el infierno fuera de cualquier VCS
• No hay marcadores de profundidad
• Documentos crecen demasiado grande y entonces se vuelven torpes: Split (y sin buscar más) o esperar años para cargar .

Answer 7

LaTeX

Answer 8

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 funciones de integración para Visual Studio.

Lo mejor es que una vez que tiene una base de documentos base importada en DocToHelp, puede elegir cualquiera de varios formatos de exportación, ya sea WinHelp, Ayuda HTML, Ayuda de Java o la agradable y elegante Net Help.

Answer 9

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

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

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

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

Answer 10

Para dolar el código utilizo Doxigen. Prefiero la versión de Linux, tuve problemas con algunas funciones en la versión de Windows

Answer 11

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 criterio de "marcado fácil", pero definitivamente produce un buen resultado en LaTex (se puede convertir luego en PDF) y un buen resultado en HTML si prepara su propia hoja de estilo CSS. Archivos de texto guardados en el control de la versión.Todos los programas también usan una biblioteca que combina el análisis de argumentos de línea de comandos con la salida "--help" en una selección de formatos (normal, página de manual y libro de doc). Para la referencia API, doxygen, por supuesto.

Answer 12

En mi trabajo actual, creamos software de un solo uso para que la documentación a menudo se coloque en la línea lateral y se haga en Word.

En mi último trabajo, sin embargo, el equipo de documentación parecía despotricar continuamente sobre mad cap software's product "Flare". Le permite escribir en un formato y publicar en muchos medios para que su manual también sea su ayuda en línea o un sitio web, etc.

Answer 13

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

Answer 14

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

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

Answer 15

No puedo decir suficientes cosas buenas sobre Asciidoc. Tiene una sintaxis de marcado muy simple, puede generar de todo, desde PDF hasta roff, ser portable de implementar y muy fácil de insertar en cualquier wiki con solo unos pocos cambios menores.

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

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

Para la doumentación del código, uso Doxygen.

Answer 16

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

Desde el sitio Pandoc:

Si usted necesita para convertir archivos de un formato a otro marcado, Pandoc es su navaja suiza del ejército. Pandoc puede leer de rebajas y (subconjuntos de) reStructuredText, textil, HTML y LaTeX, y puede escribir texto sin formato, de rebajas, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, XML DocBook, XML de OpenDocument , ODT, GNU Texinfo, marcado MediaWiki, textil, groff man páginas, Emacs org-mode, ebooks EPUB, y presentaciones de diapositivas S5 y Slidy HTML. PDF de salida (a través de LaTeX) también es compatible con el incluido markdown2pdf envoltorio script.

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

Answer 17

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