software - documentation traduccion
La compañía insiste en usar un formato binario para toda nuestra documentación (19)
¿Insisten en que lo escribas en Word o solo que esté disponible en formato Word? Puede escribir en un formato de texto y convertirlo a Word automáticamente.
Trabajo en una empresa que, por alguna razón, insiste en que toda nuestra documentación de desarrollo debe estar en formato MS Word. Lo cual, al ser un formato binario, significa que no podemos:
- Versiones diferentes de un documento en contra de la otra (por lo que la revisión por pares es un dolor; debido al dominio en el que trabajamos, las revisiones por pares para todos los cambios son esenciales)
- Grep una carpeta llena de documentos para palabras clave
¿Qué usas para escribir la documentación y por qué?
Por favor, también dame munición para cambiar esta situación con ...
¿Todo el equipo de desarrollo está en contra de este requisito o es un grupo pequeño? Si se trata de todo el equipo, simplemente ignore el mandato y use un formato basado en texto: no sería la primera vez que los empleados ignoran una regla tonta. Funciona especialmente bien si no has hecho mucho alboroto en el pasado. Si es así, la administración puede ser especialmente dura en sus documentos.
Al menos puede comparar documentos de Word, ver el comando "Seguir cambios" en el menú "Extra", o usar software como DeltaView . Encontrado a través del primer enlace de la búsqueda de google en lifehacker.com . La búsqueda en documentos de Word debe ser posible con Google Desktop Search u otros programas similares que indicen todos los archivos que pueden leer.
Creo que hay programas que convierten documentos de Word en texto sin formato. Use uno de ellos para convertir la palabra doc a texto sin formato y luego use diff, grep, etc.
Debe ser fácil automatizar la palabra para extraer todo el texto de un documento de Word en un archivo de texto. De modo que podría escribir una secuencia de comandos creando archivos de texto desde documentos de Word, y grep, compare, control de versiones, Revisar estos archivos de texto.
Por supuesto, esta no es una solución ideal, ya que pierde su bonito formato, pero debería funcionar.
Hay muchas herramientas para la comparación de documentos de Word. Actualmente uso una secuencia de comandos python que pone una línea de comando en la funcionalidad incorporada de comparación y fusión de la palabra.
MS Word admite el seguimiento de cambios de documentos y la revisión por pares.
El nuevo formato de MS Office está completamente basado en XML (para ver esto, cambie el nombre de un archivo .docx de MS Word a .zip, luego descomprímalo para verlo).
¿Tal vez Office 2007 puede ajustarse tanto a los requisitos de su empresa como a sus inquietudes?
No para defender los productos MS aquí, pero MS Word puede diferenciar documentos.
Para la munición, está el viejo programador pragmático, el capítulo 14: El poder del texto simple.
Como programadores pragmáticos, nuestro material base no es madera o hierro, es conocimiento. Reunimos requisitos como conocimiento y luego expresamos ese conocimiento en nuestros diseños, implementaciones, pruebas y documentos. Y creemos que el mejor formato para almacenar conocimiento persistentemente es el texto plano . Con texto sin formato, nos damos la capacidad de manipular el conocimiento, tanto de forma manual como mediante programación, usando prácticamente todas las herramientas a nuestra disposición.
Si usa Beyond Compare como la herramienta diff para su sistema de control de origen (como lo hacemos, con Perforce), le mostrará las diferencias entre las revisiones de sus documentos de Word. Es cierto que solo muestra las diferencias textuales, no se muestran los cambios de formato, pero esto suele ser suficiente para que usted vea qué cambió.
Esta es solo otra razón para invertir en Beyond Compare, ya que es uno de los software más refinados que he usado en mi vida, y es el mejor de los $ 30 dólares (menos si compra varios) que he gastado en software.
Un formato textual facilita la fusión de su documentación con elementos generados tales como JavaDoc, referencias API o diccionarios de datos. También escala mucho mejor que la palabra, que es difícil de usar para documentos grandes. Finalmente, un formato que permite inclusiones permite que varios autores trabajen en un documento al mismo tiempo.
LaTeX y FrameMaker (los dos sistemas que he usado para esto) tienen capacidades de indización y referencias cruzadas muy superiores y tienen un formato textual nativo o una versión textual de su formato nativo que se puede incluir (MIF en el caso de Framemaker) . También son mucho más estables que la palabra.
Creé herramientas que leen diccionarios de datos y generan documentación que se puede incluir en un documento más grande con indexación estable y referencias cruzadas bidireccionales. La especificación funcional para este producto se hizo con LaTeX de esta manera y me consiguió otro concierto con la empresa. También he desarrollado un proceso similar con FrameMaker.
Usamos una wiki (específicamente la proporcionada por Trac) por las dos razones que usted mencionó. Además, si realmente lo necesitamos, podemos obtener la versión de texto del marcado y manipularlo también en un entorno de solo texto (por ejemplo, como parte de los comentarios de svn durante la confirmación).
Un formato que se puede reducir fácilmente a texto solamente (no binario) es definitivamente una necesidad. Tener la capacidad de convertirlo a un formato bonito como un PDF es, para nosotros, no demasiado importante.
Usamos una wiki, específicamente Confluence by Atlassian .
Es un producto comercial, y es genial. Una de las razones por las que elegimos los motores wiki gratuitos / abiertos es que tiene un editor WYSIWYG completo y varias otras características que lo hacen más accesible para los usuarios que están familiarizados con Word.
También hemos creado un truco ingenioso donde almacenamos imágenes, diseños, wireframes, etc. en Subversion, y luego incorporamos enlaces en los documentos wiki a esas URL de recursos a través del módulo de interfaz web Apache / SVN; notas sobre cómo hacemos esto están aquí si estás interesado.
Word tiene seguimiento de cambios para documentos (aunque solo funciona hasta que acepte los cambios) y también puede grep (el texto no está encriptado). Así que no estoy seguro de que ninguno de tus argumentos se mantenga bajo escrutinio. Me encantaría darte la munición para cambiar esto, pero me he vuelto cansado y cínico con la edad.
Usamos MS Word para nuestros documentos (lo cual es una gran mejora con respecto a la opción anterior (Lotus WordPro - ugh!).
Puede solicitar que la documentación esté en formato OOXML ( .docx , en el caso de Word). No es tan ideal como usar ODT, en mi opinión, sin embargo, sigue siendo solo un archivo zip con un montón de archivos XML adentro. :-)
¿No almacena archivos de documentación en algún tipo de Sistema de control de versiones, idealmente junto con el código fuente? Recomendaría hacer esto (hace que sea más fácil obtener la documentación para versiones de software antiguas).
Y si almacena los documentos en VCS, notará que los archivos de texto plano o de bases XML son mucho mejores para esto, porque puede obtener diffs; Además, los cambios entre archivos de texto generalmente se almacenan de manera más eficiente que los cambios entre archivos binarios.
Al igual que la organización de Dylan, también utilizamos la excelente wiki de Confluence . Escribí un artículo sobre por qué este es el mejor enfoque llamado Wiki es mi procesador de textos , que debería darle algunas razones para cambiar la situación.
Los beneficios de utilizar una wiki para la documentación interna incluyen los siguientes.
- Los usuarios de procesadores de palabras se dejan convencer por cambiar el diseño y la tipografía, por buenas que sean sus plantillas, lo que consume tiempo y reduce la coherencia.
- Una wiki proporciona búsqueda de texto completo, que es poco probable que tenga para su cuerpo los documentos de MS Word escritos por todos.
- Una wiki proporciona un historial de versiones de documentos; Nunca escuché de un equipo mantener todas las revisiones en documentos de Word y siempre poder comparar versiones antiguas o usar un sistema de control de versiones (con la posible excepción de SharePoint, pero ese es un escenario de falla completamente diferente).
- Una wiki hace que los hipervínculos entre documentos sean fáciles; es demasiado difícil vincular de manera confiable los documentos en una colección de documentos de Word, por lo que los nuevos documentos terminan duplicando contenido antiguo en nuevos documentos monolíticos, lo que significa que se toman más tiempo para leer y escribir.
- Las diferentes páginas wiki pueden ser editadas por diferentes personas al mismo tiempo, y Confluence puede fusionar los cambios cuando varias personas editan la misma página al mismo tiempo; la colaboración es más difícil con un documento de Word que solo una persona puede editar a la vez.
- Un wiki como Confluence genera automáticamente páginas de navegación basadas en la estructura y las etiquetas wiki; necesita un bibliotecario y mucha disciplina para que sea posible navegar por una gran colección de documentos de Word.
- Una página wiki generalmente se carga y muestra más rápido que un documento de Word.
- Una página wiki tiene más metadatos automáticos; necesita plantillas y disciplina para asegurarse de que los documentos de Word siempre tengan el título, el autor y la versión establecidos en las propiedades del documento y sean visibles en el documento en pantalla y en forma impresa.
Si quieres más municiones que esta, entonces hay mucha promoción de wiki en The Atlassian Blog .
Recientemente comencé a usar DocBook XML para autorizar mi documentación.
Por el lado positivo, es un formato de texto puro. Puede dividir un documento grande en varios archivos y usar nodos para reunirlos en un solo libro. La tabla de contenido y el índice se generan automáticamente. Los enlaces dentro del documento (dentro de texto arbitrario, señalando capítulos o secciones) son muy fáciles. Y con solo presionar un botón, puedo crear una versión de archivo html único, una versión html fragmentada (un archivo por capítulo) y una versión PDF.
Después de algunos ajustes y personalización, estoy muy contento con la salida. ¡Los documentos se ven geniales !
DocBook es utilizado ampliamente por editores reales (más notablemente, O''Reilly), y ha existido por más de quince años, por lo que ha alcanzado un cierto nivel de madurez.
Por otro lado, todo el procesamiento se realiza con XSLT, utilizando una colección de herramientas ad-hoc. (Mi propia cartera de docbook incluye Python, Java, Xerces, Xalan, Apache FOP y PDF-SAM. Más la distribución oficial de hojas de estilo XSLT y mis propias personalizaciones XSLT).
DocBook no es una solución lista para usar. No podrá ponerse en marcha rápidamente, sin leer el manual. Y si no sabes nada sobre XSLT, tendrás que aprender.
Por otro lado, solo hay una docena o dos etiquetas XML que realmente necesita saber para escribir los documentos. (La experiencia real entra en juego durante la generación de documentos a partir de las fuentes XML.) Si una persona de tu equipo estaba dispuesta a ser responsable de escribir el script de construcción de documentos, entonces todos los demás en el equipo podrían simplemente aprender el DTD y hacer un trabajo decente. contribuyendo
De todos modos ... DocBook definitivamente tiene algunas fallas. No es el sistema más fácil para la autoría de tecnología. Pero es la mejor herramienta de código abierto que conozco.
El "Libro de Subversion" está escrito en DocBook. Aquí hay una página con enlaces a las diferentes versiones de libros (single-html, chunked-html y PDF):
Y aquí hay un enlace a las fuentes XML de DocBook para el primer capítulo, para que pueda hacerse una idea de cómo funciona:
http://sourceforge.net/p/svnbook/source/HEAD/tree/branches/1.7/en/book/ch01-fundamental-concepts.xml
También eche un vistazo a la (s) cadena (s) de herramientas recomendadas para DocBook.