Aplicación (No un Lenguaje de Marcado) para Producir un Manual de Usuario [cerrado]

Software de Publicación Técnica-Puntos de vista sobre FrameMaker y Sus Alternativas

He realizado documentos de especificaciones con LaTeX y Framemaker, y he diseñado un flujo de trabajo de Framemaker para apoyar a un equipo de 5 analistas que producen un documento de especificaciones para un sistema de suscripción de seguros. Se esperaba que el documento llegara a 2.000 páginas más o menos. Hace muchos años (alrededor de 1992-1993) también trabajé brevemente como tipógrafo.

Framemaker está diseñado para la documentación técnica y lo hace muy bien de hecho. También tiene características diseñadas para soportar documentos muy grandes con múltiples autores - la gente usa este sistema para hacer documentos con más de 100,000 páginas. También es más accesible que LaTeX para los usuarios familiarizados con el software de procesamiento de textos.

Características principales de Framemaker:

• Documentos consistentes en múltiples archivos: Puede reunir un 'Libro' con múltiples subsecciones en diferentes archivos. El documento puede también ser mantenido en control de fuente.

• Formato de texto MIF para importación / exportación: El importador es algo quisquilloso (encontré generando trabajar LáTeX para ser más fácil), pero usted puede generar elementos como datos diccionarios e importarlos en documento. El archivo tiene texto anclas (ver abajo) para que pueda crear enlaces de referencia cruzada que será estable a través de las importaciones. Me encontrar esto para ser una característica clave para especificaciones ya que permite referencias cruzadas para enlazar directamente a generado elemento.

• Potente sistema de etiquetado, indexación y referencias cruzadas: Todo se basa en etiquetas en Framemaker y es fácil aplicar etiquetas rápidamente. Esto significa que las referencias cruzadas, indexación, texto condicional y aplicar estilos en masa es fácil y solo funciona . Puede generar índices y TDC basados en etiquetas, por lo que tener múltiples índices especializados (como una lista de nombres de campos de datos desde pantallas o un diccionario de datos) es fácil de hacer. Documento Me descrito anteriormente tenía 4 índices.

• Estable: Framemaker está diseñado para profesionales para que no segundo supongo que en la forma en que word. También es mucho más estable en grandes documento. Cualquiera que haya intentado escribir un documento de más de 50-100 las páginas en Word deben tener un bonito buena idea de lo que esto implica.

• Scriptable: FM tiene una API C y hay son varios plugins de scripting (FrameScript y FMPython siendo probablemente el más utilizado) que se puede utilizar para automatizar trabajos en FM. Framemaker 10 añade soporte para una herramienta de scripting basada en Javascript llamado Extendscript, presumiblemente portado a través de la instalación de scripting en InDesign.

• Abastecimiento único: De un solo FM documento que puede producir PDF, Ayuda de Windows (CHM), HTML e impresión documentos con bastante facilidad. El las referencias cruzadas también resuelven a hipervínculo.

• Controles globales de estilo: Puede configurar fácilmente estilos para un documento y aplicarlo en todo el documento. También facilita encabezados y pies de página con un gran flexibilidad en tener los tramos de pista, versiones, capítulos etc.

Alternativas a Framemaker

• LaTeX / Lout: Ya has indicado que no quieres un marcado pero el TeX y Los sistemas Lout se utilizan para grandes documentos estructurados y hacer esto bien.

• Ventura Publisher: Probablemente el única alternativa real a Framemaker si quieres ese tipo de interfaz de usuario sin pagar partes corporales por el privilegio. Tiene un fuerte apoyo para estructurado documentos y un documento basado en XML formato de intercambio. Ahora es propiedad por Corel, que todavía parecen estar promoviendo activamente.
  

  Hay un par de otros herramientas técnicas de publicación en el mercado: Quicksilver (que antes se conocía comoInterleaf ) yArborText . Estas dos son herramientas poderosas - Interleaf solía ser el líder del mercado en este campo en un momento dado - pero bastante caras.

• Adobe Indesign: Aunque Adobe claim you can do large documents con InDesign, las referencias cruzadas y otras características de documentos grandes tienden a ser vistos como carentes por Asistente de facturación y cobranza. Hay, sin embargo, un sistema de entrada de texto para él llamado InCopy que aparentemente tiene este tipo de funcionalidad y bastante un cuerpo grande de Terceros plugins, algunos de los cuales lo hacen soporte de etiquetado y otras instalaciones similares. InDesign también tiene una API de scripting y un intérprete JavaScript para ejecutar guiones.

  No he usado Indesign, así que realmente no puedo comentar cómo bueno, funciona en la práctica.

• DocBook: Esto es realmente simplemente un formato estándar para estructurar documenta pero tiene un gran ecosistema de herramientas que lo rodean para escribir y la representación de documentos. Si si no quieres usar látex, lo harás probablemente no quiera usar DocBook para razones similares. As Vinko Vrsalovic señala (+1), Este enlace va a un StackOverflow publicación de alguien que describe el uso DocBook en la práctica. Nunca he usado realmente DocBook y he hizo tantas ediciones a este post que ahora está en modo Wiki, así que alguien familiarizado con DocBook podría quiero profundizar en esto.

• Software de procesamiento de textos: Word tiene graves deficiencias como técnica de publicación y no es recomendar. OpenOffice tiene algo mejor estructurado funcionalidad de documentación que palabra y puede ser una mejor opción si política o requisito de uso .doc como formato de intercambio de documentos excluir una mejor alternativa. Wordperfect también es considerablemente mejor para documentation-in-the-large than word y todavía tiene presencia en varios mercados verticales como oficinas legales.

• Software Madcap Llamarada y Llamarada: Estos son nuevos chicos en la cuadra y viven en aproximadamente el mismo espacio que Framemaker. La compañía fue fundada por ex eHelp (creadores de RoboHelp) empleados y es desarrollo activo, con múltiples lanzamientos anuales. Su las ofertas se han ampliado enormemente en los últimos dos años, a la en detrimento de la calidad de los productos individuales. Parece que el enfoque ha estado en la elaboración de nuevos productos y por consecuencia, hay muchos problemas de" ajuste y acabado " en cada. Los autores han optado por reinventar la rueda de muchas maneras, resultando en implementaciones confusas y a menudo rotas. Ahorre a menudo, usted encontrará excepciones sin control. Integración de control de código fuente es escamoso. Por ejemplo, mover o eliminar un grupo de archivos dará lugar a una confirmación de control de código fuente para cada eliminación de archivos. Gran PITA cuando tiene notificaciones por correo electrónico de control de fuentes. Hola 500 correos electrónicos. Flare puede importar archivos de Word y Framemaker, pero la importación está lejos de ser transparente. Espera retener todo tu contenido pero planee rediseñar completamente desde cero. Flare comparte muchas de las tendencias de Word para hacer demasiado las escenas y asumir lo que el usuario elegiría. El HTML se ve al igual que lo que sale de Word cuando se exporta HTML-un montón de etiquetas personalizadas y atributos, estilos en línea profundamente anidados, etc. El texto editor es enloquecedor, por ejemplo, su modelo de cursor es diferente que cualquier otro software que hayas usado.

Framemaker vs LaTeX

Estos dos son los sistemas principales que he utilizado para producir documentos de sistema grandes y presentables y he tenido buenos resultados con ambos.

• Facilidad de aprendizaje: TeX puede darte control absoluto, pero en realidad lograr esto en un látex complejo documento sin romper otro los artículos no son triviales, particularmente donde un gran número de macro los paquetes están involucrados. Látex básico no es difícil de aprender, pero hacer versiones modificadas de .sty archivos que todavía el trabajo requiere un poco de retoques si no eres un TeX muy profundo hackers. Se puede hacer pero ser preparado para gastar bastante tiempo jugueteando.

  Framemaker puede darle un buen grado de control sobre el aspecto del documento y no es tan difícil de aprender. Conseguir un estilo de casa y ajustar el diseño (que probablemente tendrá que hacer) será más fácil con Framemaker.

• Facilidad de entrada de texto: Puede utilizar herramientas como Lyx para proporcionar un procesador de textos-como front end para LáTeX, y estos funcionan bien si desea escribir grandes cuerpos de texto. Interfaz de usuario tipo DTP de Framemaker funciona de una manera familiar para las personas que están acostumbrados a wordproessing software. Desde esta perspectiva hay poca práctica diferencia.

• Plantilla de la estructura del documento: Framemaker permite un documento estructura a definir en términos de etiquetas o un esquema XML (si usa Framemaker estructurado). LáTeX tiene un conjunto de elementos estructurales enlatados que son lo suficientemente flexibles como para utilidad. Adición adicional elementos estructurales (por ejemplo, datos a diccionario) se puede hacer como un macro, pero haciéndolos auto-número es un poco más desafiante y que se necesidad de hurgar detrás de la escena. Ambos pueden hacerlo, pero es considerablemente más técnico para hacerlo en LaTeX en cualquier cosa menos trivial caso.

  Además, LaTeX no tiene the facility to template the estructura del documento en la forma en que Framemaker estructurado lo hace. Sin embargo, puede lograr este tipo de efecto con DocBook y luego generar a LaTeX si se desea.

• Facilidad de integración: Encontré hacer un generador para no trivialmente archivos MIF complejos para ser bastante fiddly. El analizador MIF es bastante pernickety en FM y realmente no da buenos diagnósticos. LáTeX produce mensajes de error mucho mejores y es un poco menos quisquilloso.

Software de Publicación Técnica vs. Software de Diseño

El software de diseño de página comenzó con Pagemakery los otros jugadores principales en este espacio fueron su competidor Quark Xpess y ahora InDesign, con el que Adobe esencialmente está tratando de desaprobarlo y reemplazarlo y Framemaker. Scribus , que usted mencionó antes, vive en el mismo espacio que estos productos.

Si está produciendo un manual con menos de (digamos) 50-100 páginas, uno de los paquetes probablemente haría un trabajo adecuado. Realmente están diseñados para tareas de publicación de publicidad y diseño pesado, como revistas, por lo que su soporte para funciones de documentos grandes del tipo que se encuentra en Framemaker es bastante limitado. El problema clave con estos productos es la escalabilidad : no funcionan bien en documentos grandes.

Solo como referencia, he tipografiado un libro de 200 páginas (la autobiografía de alguien) usando Pagemaker. Mientras que el el kerning de grano fino y el control principal ayudan un poco para el copyfitting, sigue siendo un proceso altamente manual para diseñar un documento del tamaño de un libro. En este caso, el libro era solo texto recto sin referencias cruzadas significativas o estructura que no sean capítulos. Hacer un documento de especificaciones técnicas complejas o un manual de este tamaño con Pagemaker habría sido muy complicado y probablemente casi imposible hacerlo bien sin ningún error.

Publicación Técnica vs. Procesamiento de Textos Software

Esta es más una descripción de las principales deficiencias de MS-Word para documentos de especificaciones grandes. Sin embargo, ilustrará algunas de las principales características requeridas para documentation-in-the-large:

• Indexación y Referencias cruzadas: Esta es una tarea real en Word, y bastante inestable. De Framemaker características de etiquetado y etiquetas de LaTeX significa que puede asignar una etiqueta o etiqueta conocida (en un formato predecible si es necesario). El formato textual para la etiqueta anclas está expuesto en la interfaz de usuario, y se utiliza para vinculación. En la palabra, las anclas son mucho más opacos y no fácilmente controlable de esta manera. Combinado con el usuario torpe interfaz e inestabilidad de la producto, esto hace que el mantenimiento estos fiddly, y a menudo inestable - a menudo tienes que arreglarlos manualmente hasta.

• Diseños templados: El soporte de estilo en word es bastante básico y la numeración tiende a ser algo inestable. FrameMaker es todo sobre conducir desde las etiquetas y la aplicación estilos basados en las etiquetas. Global los cambios de estilo solo funcionan en Framemaker de una manera que no lo hacen en Word.

• Documentos multi-archivo grandes: Nunca he sido capaz de hacer que esto funcione bueno en palabra, pero es una clave característica en Framemaker y LaTeX. Una vez más, la inestabilidad de Word significa que tiendes a pasar mucho tiempo ordenando después. Como el documento se hace más grande, el proporción del tiempo dedicado a esto el trabajo crece cuadráticamente - propensión a rotura proporcional to n (tamaño del documento) * time to arreglo proporcional al tamaño n (tiempo para fijar)

• Por qué Word es tan inestable: Word hace mucho entre bastidores para apoyar a los usuarios novatos e intervenir en diseños. Tampoco es realmente basado en marcos (flujo de texto conceptualmente separado del diseño del documento), pero los desarrolladores intentan implementar varios comportamientos de fotogramas en la interfaz de usuario. Cuando la A. I. segundo-te adivina en un documento complejo a menudo hace el cosa equivocada. Framemaker ' trata el usuario como adulto ' y no hace ninguno de esto para que las cosas se queden donde pones ellos.

  Otros procesadores de texto como Open Office y WordPerfect no lo hacen se portan mal de la misma manera que Palabra, que es una de las razones que casi cualquier palabra procesador que no sea Word hará un mejor trabajo de los documentos técnicos.

• Pre-Flighting: En el lenguaje de la documentación, este es el proceso de comprobación de que su ensamblaje de archivos para el documento (archivos de imagen, etc.) es correcto antes comprometerse a imprimir. El los sistemas profesionales se quejarán acerca de las cosas que están mal, dando la oportunidad de corregirlo. Palabra se acaba de poner en una cara feliz y trata de arreglar las cosas entre bastidores.

  Un buen ejemplo de esto es una palabra archivo con gráficos vinculados. Si copiar el archivo y los gráficos a otro directorio y actualizar uno de los gráficos in situ, palabra bien puede todavía leer el archivo de la antiguo camino (lo he visto hacer esto) y no el nuevo que acabas de actualizar. Sin embargo, este comportamiento no es consistente y tipifica el abuso desenfrenado de heurística inestable en ese producto.

• Soporte de preimpresión: Un sistema de publicación se extiende a la preimpresión fase del flujo de trabajo. Esto significa cubre la preparación para la impresión. El software de procesamiento de textos no tiende a tener esta funcionalidad o tener en una forma muy limitada.

Sin llegar demasiado lejos en esto, una diferencia clave es que el software de publicación tiende a tratarte como un adulto que consiente y no se interpone en el camino cuando quieres escalar o automatizar las cosas. One puede usar software de procesamiento de textos para documentación a gran escala, pero tiene muchas decisiones de diseño adaptadas a usuarios ocasionales que escriben documentos cortos con poca consideración por la calidad. Estas adaptaciones se producen a expensas de la aptitud para la tarea en el trabajo de preparación de documentos a gran escala. Los principales problemas que encuentro con Word para los documentos de especificaciones son la pobre indexación y referencias cruzadas y los problemas generales de inestabilidad en los que siempre tengo que volver y arreglar las cosas. Sin embargo, las consideraciones políticas en la mayoría de los entornos (soy un contratista) significan que uno a menudo se queda con él.

Algunas observaciones generales sobre el estado del software de documentación técnica

Framemaker sería la opción obvia si Adobe no siguiera emitiendo señales de que están tratando de desaprobarlo y mover su base de usuarios a InDesign. Sin embargo, FM es ampliamente utilizado en los círculos aeroespaciales, de software y de ingeniería y la gestión de Adobe se enfrentaría a un linchamiento si realmente EOL'd el producto sin una ruta de migración creíble. Por lo que se lee en la web, la adquisición de FM por Adobe fue impulsada por John Warnock, pero fue derrocado y FM se convirtió en víctima de la política de la oficina. El resultado neto es que se ha movido al modo de mantenimiento y está bastante estancado.

Ventura Publisher también ha sido relegado a un nicho de mercado hasta cierto punto, pero al menos Corel no tiene dos líneas de productos competidores de la manera en que Adobe lo hace. Es probablemente un sustituto aceptable para FM y puede ser más políticamente aceptable para los tipos de PHB, ya que se comercializa como un sistema de "publicación de negocios".

Quicksilver y Arbortext parecen ser productos viables, pero son muy caros. Yo tampoco he usado, así que no puedo hacer ningún juicio real sobre sus méritos.

Los sistemas de lenguaje de marcado son libres y muy poderoso en muchos sentidos. Podría ser un poco más fácil trabajar con Lout, ya que no tiene el nivel de equipaje heredado que LaTeX. DocBook también es muy utilizado y tiene bastante soporte para herramientas. Estas tecnologías ponen un apretón significativo en el extremo' geek ' de la cuota de mercado de Framemaker y lo hacen por sus méritos - probablemente han tomado una buena parte de los márgenes de beneficio de Adobe a lo largo de los años. Yo no descartaría estas tecnologías de las manos, pero ellos será más difícil de aprender en la práctica.

Puede intentar evaluar InDesign y un conjunto seleccionado de complementos (concéntrese en los de etiquetado y administración de referencias cruzadas/índices). Finalmente, algunos de los programas de procesamiento de textos (Wordperfect y OpenOffice) le proporcionan un kit de herramientas razonable para la documentación estructurada y funcionan considerablemente mejor para esto que MS-Word.

PostScript

Sí, eso es un juego de palabras. No he tocado la funcionalidad de preimpresión de ninguno de estos producto. La impresión y la preimpresión son campos técnicos por derecho propio y el alcance de errores costosos significa que probablemente debería dejar esto en manos de especialistas. Framemaker, InDesign, Ventura, QuickSilver, Arbortext y (presumiblemente) los productos MadCap vienen con instalaciones para hacer la preparación de preimpresión. En general, el software de procesamiento de textos no lo hace.

Hacer preimpresión con LaTeX tiende a implicar el postprocesamiento de la salida PS con software como psutils o renderizado a PDF y tomando el flujo de trabajo de preimpresión desde allí. En general, la mayoría de las casas de preimpresión pueden trabajar desde PDF, por lo que una buena herramienta de escritura PDF como Distiller es la mejor interfaz para el trabajo preparado con herramientas que no están diseñadas para el trabajo de preimpresión. Tenga en cuenta que la calidad de la salida de Distiller tiende a ser mejor que el Ghostscript como PDFCreator.

Tenga en cuenta que el espacio de color RGB de un monitor no tiene un mapa directo a un color CYMK espacio utilizado por una imprenta. En realidad, conseguir que los colores - especialmente las fotos en color-salgan correctamente en una prensa es algo tenso si no tiene el kit correcto. Para la producción de impresión, consulte a un especialista a menos que tenga razones para creer que sabe lo que está haciendo. Para un usuario casual, todavía recomendaría esto 15 años después de estar involucrado en la industria, ya que los errores son muy caro de arreglar una vez que se comprometen a imprimir.

Si realmente quieres para realizar el trabajo de impresión en color internamente, es probable que necesite calibrar su monitor. Para obtener mejores resultados, debe obtener un monitor de alta fidelidad como este de HP. Para calibrar el monitor también puede necesitar un sensor como uno de los descritos en esta revisión si el monitor no viene con uno. La mayoría de las tarjetas gráficas profesionales como estas de Nvidia, AMD o Matrox tienen instalaciones para admitir gamma corrección; muchos consumidores también lo hacen. También tendrá que obtener datos de calibración para la prensa que va a utilizar para imprimir, aunque la casa de preimpresión probablemente será capaz de hacer esto.

Como se indicó anteriormente, los medios impresos son bastante técnicos en sí mismos, fáciles de equivocarse y costosos de arreglar una vez que se han ido a imprimir. Si no está 100% seguro de que tiene la calibración correcta, obtenga una prueba de color como un Chromalin . Esto se hace a partir de la película real separaciones (y por lo tanto es bastante caro), por lo que da una interpretación precisa del color real del artículo impreso final. Hacer esto para algunas páginas de ejemplo le dará información precisa sobre si su calibración está configurada correctamente.

Agradecimientos: Gracias a Aidan Ryan por expandir la sección sobre productos Madcap.