consejos necesidad - Desarrollo de un sistema de documentación flexibles, muy centrado en la localización [cerrar]

Question

Me han acusado de la construcción de un sistema de documentación / plataforma.

He aquí una breve lista de los principales requisitos:

• fácilmente localizada: Esto tendrá que soportar una docena de idiomas fuera de la puerta. (La capacidad para que el personal no técnico para añadir / actualizar traducciones sería una gran ventaja, aunque no es 100% necesario)

• La flexibilidad en los formatos de salida: A lo mínimo, lo que necesito para dar salida a los documentos (ya sea en su conjunto o en trozos seleccionados) como PDF y HTML. Los puntos de bonificación para formatos nativos como Windows archivos de ayuda.

• Gestionado y desplegado a través de una interfaz de usuario intuitiva (web, idealmente).

Me pregunto si ustedes, la gente sabe de cualquier sistema por ahí que soporten este tipo de cosas ya? No soy reacio a escribir este a partir de cero, pero yo prefiero no reinventar la rueda si puedo evitarlo.

Los dos principales candidatos que he encontrado hasta ahora son DocBook y Resto . El primero parece haber ganado una reputación para, así, la succión. Estoy familiarizado con cualquiera, pero me han dicho que el descanso me conseguiría una porción buena parte del camino.

¿Alguna otra sugerencia? ¿Sería mejor construir esto desde el principio?

Answer 1

Puedo recomendar DocBook si es necesario crear documentación técnica tradicional: libros, divididos en capítulos, divididos en secciones, etc. Creo que hay tres cosas principales a considerar: el margen de beneficio en sí, el conjunto de herramientas de edición y publicación de la cadena de herramientas .

marcado. El marcado XML DocBook es muy completo, que contiene soporte para casi todos los aspectos imaginables de lo que podría ser incluido en un volumen techical y algo más. Esto incluye el material básico para libros como referencias cruzadas, notas al pie, etc., así como el marcado específicamente para documentación de software, como listados de programas, etc. La referencia entradas de referencia esencial para el marcado es DocBook: The Definitive Guide por Norman Walsh y Leonard Muellner

.

El idioma del contenido se puede marcar explícitamente el uso de atributos lang, por lo que el documento de origen puede contener el contenido en varios idiomas, y la versión en idioma deseado puede ser extraído en la etapa de procesamiento.

Herramientas de autoría. Debido al gran tamaño del vocabulario DocBook, una especie de editor de "esquema-consciente" es prácticamente un requisito. Un editor de buena le ayudará con la elección de los elementos de marcado y se asegurará de que usted produce marcado válido. Un editor de XML decente va a hacer, pero dependiendo de cómo sus autores técnica de documentación son, también podría considerar algo más fácil de usar. Hay algunos editores de estilo WYSIWYG disponibles. (He utilizado XMLmind XML Editor , y yo estaba muy contento con él.)

Herramientas de publicación. La forma estándar de-facto de generar salida de marcado DocBook XML es el DocBook XSL distribución de estilos. Tiene soporte para los formatos de salida multple, incluyendo HTML, XSL-FO (para la salida PDF), la Ayuda HTML, incluso páginas man. La salida generada por el estilo puede ser controlada por muchos parámetros, y lo primero que debe consultar cuando se desea sintonizar la salida es la documentación de referencia distribuyen con las hojas de estilo.

Si y cuando se desea un mayor control sobre la salida producida, sin embargo, es necesario personalizar las hojas de estilo XSLT para su uso particular. Esto puede parecer un tanto desalentador, especialmente si usted no tiene experiencia previa de XSLT. Sin embargo, hay un excelente libro libre disponible sobre el tema: DocBook XSL: The Complete Guide por Bob Stayton.

Para convertir XSL-FO a PDF, usted también necesita un procesador XSL-FO. Ahí está el código libre y abierto Apahce FOP en cuando hay múltiples opciones comerciales.

Lo más probable es que su proceso de publicación probablemente va a terminar pareciéndose a un sistema de construcción para su documentación. Vas a tener un sistema automatizado (probablemente impulsado por una herramienta de construcción como el maquillaje o ANT) que se llevará a su fuente de documentación en XML y convertirlo en formatos de salida deseadas en los idiomas deseados.

---

En resumen, yo diría que DocBook es una buena opción si usted está buscando para producir en forma de libro, la documentación técnica detallada lineal. Las principales desventajas son la complejidad del margen de beneficio, que puede presentar una curva de aprendizaje considerable para los autores, y que puede hacer que las herramientas especiales necesarias autoría. Además, la personalización de la salida de las hojas de estilo DocBook XSL puede llegar a ser muy involucrados.

Si usted está buscando para producir menos "tipo libro" y más "en línea" similar a la documentación - temas de la documentación interrelacionadas entre sí - es posible que desee echar un vistazoen DITA otra alternativa basada en XML. Yo no lo he utilizado, pero también viene con un conjunto de herramientas para la producción de varios formatos de salida desde el marcado XML.

Answer 2

DocBook y reStructuredText son sin duda los dos competidores más grandes, pero AsciiDoc es otro, similar lenguaje de marcado que se puede leer independientemente de la marca. Estoy más familiarizado con (y por lo tanto un autor mayor de) reStructuredText, en lo personal, pero AsciiDoc es sólo otra opción que hay.

Teniendo en cuenta lo que usted ha descrito hasta ahora, suena como MoinMoin sería un buen ajuste sobre la base de que que tiene una reStructuredText analizador y se puede exportar páginas PDF a . Usted debe ser capaz de extraer la fuente y ejecutarlo a través de lo que otras herramientas independientes como sea necesario (pero puede que tenga que preprocesar los que se deben eliminar cualquier tipo de código MoinMoin específica).

Google tiene algunas otras para reStructuredText wiki si ISN MoinMoin' t exactamente lo que necesita.