¿Qué herramienta/marco utilizar para la documentación técnica?

Question

Desarrollamos productos y marcos para usar en nuestra organización. Estoy buscando herramientas de documentación amigables con programadores. Recientemente investigué algunas opciones pero no pude decidir cuál usar. Estoy buscando sugerencias de las personas que ya usaron estas herramientas.

1. DocBook: Spring Framework y de hibernación uso de este formato y esto se ve bien. pero creo que han personalizado la xslt/stylesheet predeterminada. ¿Puedo copiar y usar sus xslt y css (por supuesto, con colores e imágenes modificados)? ¿Puedo integrar la generación de doc usando maven?

2. wiki: esto no es compatible con los redactores de documentos técnicos y la documentación no se ve profesional. el control de versiones tampoco es posible Creo que

3. documentos de palabras: esto es lo que usamos actualmente, pero es difícil vincular y reutilizar documentos comunes.

4. DITA?

Answer 1

DocBook

Copiar hojas de estilo: si, puede copiar y adaptar las hojas de estilo. Las hojas de estilo XSL para DocBook son muy flexibles, pero no fáciles de entender. Tendrás que poner algunos días para que funcionen de la manera que te gusta.

Integración Maven: sí, existen complementos maven donde puede integrar la generación de documentos (por ejemplo, PDF, HTML, etc.) en su proceso de compilación. Estamos haciendo eso, incluidas las marcas de agua para SNAPSHOTS solamente y la implementación en archiva en el lanzamiento.

Answer 2

No estoy seguro si usted está en busca de sugerencias adicionales o comentarios solo en los que enumeró/han reducido a, pero ...

Python utiliza una combinación de reStructuredText y Sphinx, que es una herramienta que comencé a adoptar en el trabajo y estoy disfrutando.

De las que enumeró, he usado las wiki antes y fue desagradable por muchas razones, algunas de las cuales ha mencionado. La palabra parece una mala elección también; de aquellos elegiría el docbook pero sé muy poco al respecto, así que ...

Answer 3

Estoy bastante satisfecho con DocBook aunque el aumento inicial (incluido el ajuste de las hojas de estilo) no es tan fácil. Pero una vez que todo está hecho, es realmente fácil de usar.

Ejecuto mi generación de docbook desde un Ant build.xml a través de la tarea estándar XSLT. Si Maven le permite llamar a un procesador XSLT, entonces todo debería estar bien.

El único inconveniente (me pareció) es la forma en cómo grandes libros deben ser gestionados (para evitar tener todo en un enorme fila india XML)

Cada capítulo es un archivo XML independiente que, desgraciadamente, no es una completa archivo DocBook, ya que se incluyó el uso a través de las entidades del sistema:

 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 
[ 
    <!ENTITY chapter_1 SYSTEM "chapter_1.xml"> 
    <!ENTITY chapter_1 SYSTEM "chapter_1.xml"> 
]> 

<?xml-stylesheet href="html.css" type="text/css"?> 

<article lang="en"> 
    <title>The Manual</title> 

    &chapter_1; 
    &chapter_2; 

</article> 

Entonces chapter_1.xml se parece a esto:

 
<section id="chapter_1"> 
.... 
</> 

puede haber apuesta ter soluciones por ahí, pero no las he encontrado;)

Answer 4

La misma pregunta también se ha planteado en nuestro proyecto. Hasta ese momento, utilizamos documentos simples en HTML y Word, pero estas soluciones no fueron satisfactorias.

Ahora usamos DITA y realmente lo recomiendo. Es más liviano que DocBook y se aplica muy bien para la documentación de software.

Algunos pros:

• DITA permite la separación del contenido y el estilo
• La separación del contenido y el estilo permite generar la documentación de diversos formatos, como HTML o PDF. Por ejemplo, usamos DITA para generar EclipseHelp de nuestra aplicación Eclipse basada en RCP.
• DITA define un espacio de nombres específicos de software (por ejemplo <input> o <menu-item> y similares)
• DITA se suministra con scripts de construcción para diversos formatos de salida, que se pueden adaptar fácilmente a sus necesidades específicas.

Ver también DITA Open Toolkit Project Home

Answer 5

usar un wiki.

Sus objeciones:

esto no es amigable para los escritores de documentos técnicos y la documentación no se ve profesional. el versionado tampoco es posible Creo que

Hay wikis que permiten la edición WYSIWYG. La documentación técnica para un proyecto interno de la casa no necesita "lucir profesional". El control de versiones global es un problema, pero no lo veo tan importante.

Por otro lado, la ventaja masiva de una wiki es una que no se puede valorar lo suficiente, especialmente para un producto interno: fácil de contribución y colaboración. Cada usuario del producto puede contribuir a la documentación, y si puede establecer una cultura de colaboración en la documentación, el resultado será (literalmente) diez veces más útil que el promedio "Botón X hace A, botón Y hace B" técnico documentos producidos por escritores que no están realmente usando el producto. Nadie los necesita. La gente necesita guías "Howto", glosarios, preguntas frecuentes y soluciones.

Las wikis permiten y fomentan este tipo de colaboración útil. Las herramientas de autoría "profesionales" con restricciones de acceso y procesos de aprobación lo matan.

Answer 6

También se pueden combinar enfoques:

• Uso Wiki para la autoría de tener a medida que más personas involucradas, ya que sólo los escritores tecnología. De esa manera, p. los desarrolladores o el personal de soporte pueden participar fácilmente.
• Hay herramientas que se convierten de Wiki al menos a DocBook, como DocBook Wiki o Scroll Wiki Exporter de mi empresa (http: // k15t.com /) que exporta de la wiki de Confluence a DocBook e integra las hojas de estilo de DocBook para una personalización extendida (ver más arriba los comentarios) incl. RenderX XEP.

Espero que esto ayude,

-Stefan