tutorial online language examples code documentation wiki markdown manuals

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



markdown tutorial (17)

Las solicitudes básicas son:

  • formato legible / de texto humano (para un control de versión fácil)
  • en línea (para colaboración)
  • formato fácil (markdown ok, html es demasiado)
  • formato estricto (para que los autores no inventen nuevos tipos de títulos, viñetas, etc.)
  • exportable a PDF, HTML
  • fácil copia de seguridad e implementación (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 de wiki, pero necesitaría usar archivos para almacenar o tener otros medios de "implementación" para el cliente y ser fácil de instalar / mantener. Además, debería ser gratis / barato (la confluencia es demasiado costosa)

¿Alguna sugerencia?

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

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

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

Es posible que desee evaluar la lista de características 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 también hay complementos disponibles para la exportación de PDF .

Estamos usando una wiki. Recomiendo MoinMoin porque

  • muy simple de configurar (incluso en una computadora portátil)
  • muy simple de copia de seguridad (incluso puede enviar el wiki a un sistema de control de versiones para sincronizarlo, por ejemplo, entre computadoras portátiles para uso fuera de línea).
  • 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 todos los documentos es un dolor
  • La vinculación entre bits de información es un dolor
  • Sin diferencias entre versiones
  • Formato binario que da la lata a cualquier VCS
  • Sin marcadores profundos
  • Los documentos crecen demasiado y luego se vuelven torpes: se dividen (y ya no se realizan búsquedas) o se aguardan años para cargar.

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.

La mejor parte es que una vez que hayas importado una base de documentos base en DocToHelp, puedes elegir cualquiera de varios formatos de exportación, ya sea WinHelp, Ayuda HTML, Ayuda de Java o la agradable y elegante Net Help que se puede buscar.

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 de MS Word y PDF para imprimir / enviar a los clientes. Te recomendaría 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 humilde opinión, en mi humilde opinión.

No mencionas el lenguaje / marco que estás usando. 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.

Usamos 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 corrigió 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.

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 buenos resultados 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.

Para nuestra API, usamos Doxygen , que es genial.

Por el código doy uso Doxigen. Prefiero la versión de Linux, tuve problemas con algunas funciones en la versión de Windows

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

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 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.

Durante algún tiempo utilizamos 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üidades, etc.). Más tarde, decidimos escribir nuestro propio sistema desde cero y lanzarlo como código abierto: texto de enlace . 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, mantenemos MediaWiki como una ayuda basada en la comunidad.

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 con formato en su repositorio, el seguimiento de revisión es bastante simple.

Para la documentación, uso Doxygen .

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 de Pandoc:

Si necesita convertir archivos de un formato de marcado a otro, pandoc es su cuchillo suizo. Pandoc puede leer rebajas y (subconjuntos de) reStructuredText, textile, HTML y LaTeX, y puede escribir texto sin formato, markdown, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, Marcado de MediaWiki, textiles, páginas man de groff, modo orgánico de Emacs, libros electrónicos EPUB y presentaciones de diapositivas S5 y Slidy HTML. La salida de PDF (a través de LaTeX) también es compatible con el script incluido de markdown2pdf.

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

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

Sin embargo, en mi último trabajo, el equipo de documentación parecía despotricar y entusiasmarse constantemente con el producto "Flare" del software de gorra loca . Le permite escribir en un formato y publicar en muchos medios para que su manual también pueda ser su ayuda en línea o un sitio web, etc.