Herramienta de documentación técnica completa

Fondo

Buscando unificar la documentación técnica, uniendo el contenido generado por la computadora y el usuario, utilizando herramientas de código abierto. El objetivo es escribir (o generar) contenido en un formato de archivo independiente de salida, que luego se transforma en un documento final. La siguiente figura ayuda a ilustrar cómo se conectan las piezas en general.

Arquitectura de la documentación

La solución debería ser independiente del sistema operativo.

Funciones de salida

El documento final debe incluir:

  • Mesas
  • Cifras
  • Fragmentos de código
  • Títulos numerados automáticamente (para tablas, figuras y fragmentos de código)
  • Referencias cruzadas (con hipervínculos a tablas, figuras y citas bibliográficas)
  • Títulos (hasta siete niveles; 1., 1.1., ..., 1.1.1.1.1.1.1.)
  • Apéndices (hasta siete niveles; A., A.1, ..., A.1.1.1.1.1.1.)
  • Encabezados y apéndices numerados automáticamente
  • Índice (con hipervínculos)
  • Lista de tablas (con hipervínculos)
  • Lista de figuras (con hipervínculos)
  • Bibliografía (libros, artículos, revistas, libros blancos, sitios web [con hipervínculos])
    • Variedad de formatos (APA, Chicago, IEEE, etc.)

Lo que es más importante, la estilización (a través de plantillas o codificación) debe ser posible para que toda la documentación pueda volver a generarse con una nueva apariencia. ConTeXt , por ejemplo, sobresale en esto.

Markdown y Pandoc ofrecen gran parte de esta funcionalidad, aunque no estoy seguro de si maneja referencias cruzadas, subtítulos automáticos, bibliografías y fragmentos de código.

Funciones de entrada

  • Variables entre documentos (p. ej., un nombre de servidor se documenta una vez, pero se hace referencia a la arquitectura de la aplicación y las especificaciones de los requisitos del software).
  • Editor WYSIWYG basado en navegador (posiblemente Confluence)
    • editor de tablas
    • Transclusión (extractos incrustados para ayudar al contenido de una sola fuente)
    • Colaborativo (idealmente, en tiempo real)
    • Revisiones
    • Markdown (capacidad de ver la fuente, pero se usa predominantemente como un procesador de textos moderno)
  • El contenido generado por computadora se transforma en formato Markdown:
    • Documentación del código fuente (descripciones de los paquetes, no se necesita contenido con hipervínculos); Javadocs, Doxygen, etc.
    • SNMP (nombres y direcciones IP de dispositivos de red)
    • Diagramas (entidad-relaciones, UML, GraphViz, etc.)
      • Idealmente, se podrían importar imágenes JPG, PNG y SVG
    • Lista de descripciones y claves sustitutas de la base de datos (descargadas de la base de datos)

Preguntas

¿Es posible generar un documento técnico de alta calidad que incluya una variedad tan amplia de artefactos utilizando solo Markdown como contenido de origen?

Aquí están las piezas sobre las que agradecería recomendaciones o sugerencias:

  • Incluido el código fuente (p. ej., Javadoc/Doxygen -> Markdown)
  • Posibilidad de reformatear varias salidas de comandos *nix a Markdown ( nmap, traceroute, ls, tree, df, salida SNMP, etc.); la traducción podría modificarse usando awky sed, por ejemplo.
  • Editor WYSIWYG ( alternativas de FOSS a Confluence)
  • FOSS que puede manejar la agitación de las características de salida de la fuente de Markdown en los formatos de salida deseados (PDF definitivamente y MS Word opcionalmente).
    • Si Pandoc/ConTeXt no puede lograr esta hazaña, ¿qué puede hacerlo?
  • ¿Software y/o formatos de datos (p. ej., Markdown, YAML) para integrar bibliografías y referencias cruzadas de modo que el generador de documentos (p. ej., ConTeXt) pueda utilizarlos (p. ej., RStudio ) ?

Si existe un único paquete de software que reúna todas estas funciones, también me gustaría saberlo.

Relacionado

Las preguntas relacionadas incluyen:

Software

Especificaciones

Respuestas (1)

Estoy razonablemente seguro de que funcionará un poco si podría poner algo muy parecido a lo que está describiendo usando Sphinx Docs . El área con la que podría tener problemas es la edición colaborativa en tiempo real.

  • El formato base es texto reestructurado (en lugar de rebajas), pero las entradas pueden estar en rebajas.
  • Múltiples formatos de salida
  • Múltiples fuentes de entrada, incluido el código fuente, wiki, en línea, etc.
  • Puede invocar y postprocesar múltiples herramientas durante el proceso de construcción
  • Plataforma cruzada
  • Fuente abierta
  • Produce documentación realmente atractiva.
  • Todas las funciones de salida solicitadas disponibles
  • Plantillas - Sí
  • Producir documentos de múltiples formatos de salida - Sí
  • Resaltado de sintaxis de fragmentos de código en varios idiomas gracias a Pygments.
  • Amplias referencias cruzadas: marcado semántico y enlaces automáticos para funciones, clases, citas, términos del glosario y piezas de información similares.
  • Buen soporte de internacionalización usando gettext.
  • Extensible y activamente desarrollado.
Gracias. Parece que hay un generador de XML, que podría usarse con ConTeXt. así como lo que parece ser una extensión del constructor ConTeXt .
En un ejemplo con un apéndice, los números de encabezado no usan letras. Sin embargo, esto podría haber sido un descuido o una configuración incorrecta del motor utilizado para generar el PDF.
Acabo de ejecutar algunas pruebas basadas en docutils.sourceforge.net/docs/ref/rst/… y funcionan bien para la enumeración automática, incluso los números romanos.
Herramienta de documentación técnica completa
RespuestasAquíPolítica de privacidad1y, 0v