MS Word nos lanza regularmente "sorpresas": capturas de pantalla "movidas", tablas "flotantes", páginas en blanco al imprimir. Este artículo trata sobre cómo estábamos buscando un reemplazo para MS Word (no encontramos un spoiler), pero encontramos una oportunidad para mejorar nuestro proceso de trabajar con la documentación a nivel mundial.
En Uniscan Research, hacemos de los productos de alta tecnología un producto en serie. La compañía opera en los sectores B2G (empresa a gobierno) y B2C (empresa a cliente).
Nuestro departamento desarrolla documentación de diseño y de usuario para productos que se están desarrollando, documentos de certificación, materiales de marketing, diseño y decoración de oficinas (navegación, letreros de puertas).
Con documentos en el sector B2C, hay libertad para elegir el formato, el nombre y el contenido de la documentación. En el sector B2G, aproximadamente el 70% de la documentación que desarrollamos debe prepararse de acuerdo con los requisitos del ESKD y presentarse para su aprobación al cliente en el formato DOCX.
Transmitimos al usuario toda la documentación operativa en forma impresa, por lo que todos los documentos se someten a una preparación previa a la impresión. Nuestros documentos tienen dos formatos de destino: DOCX y PDF.
Para la implementación de nuestras tareas, el departamento ha usado tradicionalmente MS Word durante muchos años.
Con cada nueva edición de un documento compilado en MS Word, en aproximadamente la mitad de los casos las capturas de pantalla se "deslizan", las tablas con iconos "flotan", y cuando se imprime un documento, aparecen de repente páginas invisibles en blanco. Estas operaciones de diseño de documentos le quitan al autor del documento no solo el tiempo, sino también el deseo de participar en la creatividad: el desarrollo de nuevos documentos.
Durante la siguiente búsqueda de páginas invisibles en blanco en un documento DOCX en nuestro departamento, surgió la idea de probar una nueva herramienta de desarrollo de documentación. Queríamos reducir el tiempo de diseño y la preparación de preimpresión del documento.
Como resultado, no pudimos escapar completamente del uso de MS Word, pero en el proceso de búsqueda creamos un nuevo esquema para trabajar con la documentación.
A continuación, trataré de decirle qué herramientas para trabajar con los documentos que consideramos, por qué nos decidimos por Confluence como resultado, qué problemas encontramos y cómo pudimos resolverlos.
Selección de herramienta
Leímos artículos sobre el tema de las herramientas de desarrollo de documentación existentes, conversamos con colegas de otras compañías. Las siguientes herramientas nos parecieron más adecuadas:
- Dita
- DocBook XML
- Confluencia
Las dos primeras herramientas no encajaban por la misma razón: necesitábamos habilidades de programación que no teníamos, y para crear una nueva plantilla de documento tendríamos que pedir ayuda a un programador. La transición para trabajar con ellos, de acuerdo con nuestras ideas, tomaría unos seis meses, posiblemente más. Debido a las desventajas anteriores, decidimos abandonar la prueba completa de estas herramientas.
La confluencia desde el principio complació
al editor
WYSIWYG . En promedio, los escritores técnicos tardaron aproximadamente una semana en dominar la herramienta, el diseño de documentos "no de acuerdo con GOST" fue más fácil.
En los proyectos B2G, el PDF es importante para nosotros como formato para la documentación del usuario. Por lo tanto, instalamos inmediatamente el complemento apropiado para Confluence - Scroll PDF Exporter. Con él, intentamos crear plantillas personalizadas con los parámetros necesarios. Quedamos satisfechos con los resultados de la prueba: realizamos uno de los documentos con una gran cantidad de capturas de pantalla y elementos gráficos en MS Word durante aproximadamente una semana; En Confluence, logramos diseñar el mismo documento en 2 días y lograr una mejor presentación visual.
También intentamos configurar la plantilla para Scroll Word Exporter de manera que se emitiera un documento de acuerdo con todas las reglas de ESKD. Después de dos días de leer las guías de Exportador de PDF de Confluence and Scroll e intentar personalizar la plantilla de especificaciones técnicas actual, nos dimos cuenta de que esta herramienta no es adecuada para el desarrollo de documentos ejecutados de acuerdo con los requisitos de ESKD.
Entonces, por ejemplo, no pudimos hacer títulos numerados no grasos del segundo nivel, por lo que el texto no era un título, sino un párrafo. Tuve que escribir manualmente el número de párrafo y usar el estilo de párrafo. Era imposible organizar listas con viñetas con un guión (solo círculos, cuadrados), las listas numeradas se dibujaban sin un punto y las listas de letras solo tenían letras latinas. La sangría se ajustó solo manualmente.
Unos meses después de que comenzamos a dominar Confluence, los desarrolladores de la herramienta implementaron la función de editar documentos en su formato original. Esto nos permitió almacenar nuestros documentos "invitados" y crear nuevos documentos que no requieren una ejecución estricta en el mismo lugar. Los archivos de MS Word se almacenan en Confluence como archivos adjuntos, cuando se editan, se abren y guardan en MS Word en la PC del usuario, y cuando se guardan, la nueva versión se carga automáticamente en Confluence.
Entonces se nos ocurrió la idea de utilizar Confluence como una herramienta que resolvería simultáneamente tres problemas:
- Creando una base de conocimiento.
- Desarrollo, almacenamiento y actualización de documentación desarrollada no de acuerdo con GOST.
- Almacenamiento y actualización de documentación desarrollada de acuerdo con GOST.
Confluencia potencial
Nuestras expectativas con respecto a la funcionalidad Confluence no se cumplieron por completo, pero después de que se completaron las pruebas, se formó una actitud generalmente positiva hacia esta herramienta. A continuación formulamos sus principales ventajas para nuestro departamento:
- Personaliza y apoya la herramienta por tu cuenta.
- Fácil de aprender
- La capacidad de organizar una base de conocimiento sobre los productos de la compañía y almacenar toda la documentación compilada en DOCX y PDF en un solo lugar.
- Soporte para documentos versionados.
- Capacidad para usar tecnología de fuente única.
- La posibilidad de trabajo conjunto de desarrolladores y escritores técnicos sobre documentos.
- Almacenamiento de documentos de trabajo e información en un solo lugar.
- La capacidad de desarrollar documentos en cualquier momento desde cualquier parte del mundo.
Implementación
Para implementar Confluence, seleccionamos dos especialistas del departamento de redactores técnicos que estudiaron y probaron las capacidades de la herramienta.
Para soporte técnico continuo, el departamento de administradores de sistemas nos asignó un especialista. Respondió rápidamente a problemas técnicos y ayudó a comprender la configuración básica de la nueva herramienta.
Al mismo tiempo, creamos un grupo de trabajo en el departamento de redactores técnicos, cuya tarea era planificar la estructura de almacenamiento de datos. Toda la estructura de nuestro servidor se dividió en categorías correspondientes a los tipos de proyectos de la empresa. Las categorías, a su vez, se dividieron en espacios por productos de la empresa. También identificamos una categoría separada para la base de conocimiento interno.
Cuando los responsables de probar los sistemas estudiaron el trabajo en Confluence con bastante profundidad, comenzó la etapa de capacitación entre pares. Se tardó aproximadamente un mes en transferir el conocimiento a todo el departamento.
Problemas técnicos
La implementación de Confluence en su conjunto fue bastante fluida, pero hubo problemas.
Diseño y preparación previa de documentos.
“Solía hacerlo en MS Word en un par de segundos. ¿Cómo hacer lo mismo en Confluence? - Nos hicimos esa pregunta todos los días durante todo el período de prueba.
Por lo tanto, no era del todo obvio cómo alinear el contenido de la tabla verticalmente o asignar un tamaño de icono inferior a 16 px.
De hecho, el conjunto básico de funciones de formato de página en el editor Confluence WYSIWYG es mucho peor que MS Word, pero la funcionalidad se puede ampliar significativamente si entra en modo de edición de código fuente y trabaja directamente con código HTML.
Leímos artículos, vimos videos de capacitación sobre diseño HTML y compartimos las soluciones que encontramos. Creamos una página separada en Confluence, donde colocamos información útil sobre cómo trabajar con esta herramienta.
Confluencia y actualización de complementos
Después de la primera actualización del complemento principal de Exportador de PDF de desplazamiento, el 80% de las macros se voló y la estructura de la página fue a Confluence. Más tarde resultó lo que sucedió debido a la nueva funcionalidad del complemento. En todo el departamento, restauramos la estructura de los documentos durante varios días. Después de eso, hicimos un plan de actualización para el futuro, al que aún nos adherimos:
- Realice la actualización el viernes, cuando se haya completado la capa principal de trabajo de la semana para poder eliminar posibles problemas el fin de semana.
- Distribuya a todos los usuarios del sistema para informarles sobre la hora de la actualización planificada.
- Antes de actualizar, haga una copia de seguridad del servidor.
- Actualiza la versión de Confluence.
- Pruebe el servidor, asegúrese de que toda la información esté en su lugar, los enlaces a recursos externos e internos funcionan.
- Si necesita actualizar los complementos, haga una copia de seguridad del servidor nuevamente.
- Actualice sus complementos un complemento a la vez.
- Pruebe el complemento inmediatamente después de la actualización.
Notificaciones masivas
Cuando la actividad turbulenta de los escritores y desarrolladores técnicos finalmente comenzó a hervir en Confluence, el administrador recibió llamadas de los usuarios del servicio. Pidieron salvarlos de un ataque masivo mediante notificaciones por correo sobre las acciones de otros usuarios.
Por defecto, el usuario solo tenía que ir a alguna página una vez, después de lo cual el sistema lo agregaba automáticamente a la lista de observadores y recibía notificaciones cada vez que se cambiaba esta página.
Además de esto, Confluence hizo amablemente boletines semanales para los usuarios que enumeran las páginas más populares de Confluence. Afortunadamente, este problema ya ha sido ampliamente cubierto en Internet. La solución es deshabilitar las notificaciones correspondientes en la configuración del sistema:
Ahora los usuarios reciben notificaciones solo si su nombre se menciona en los comentarios del artículo.
Estabilidad del servidor
Para probar Confluence, implementamos un servidor de Windows. En las etapas iniciales, el servidor a menudo "fallaba". Parte del problema resultó ser insuficiente RAM en el servidor (el tamaño recomendado es 11-12 GB). Los problemas restantes desaparecieron cuando activamos la configuración del sistema recomendada en tales casos.
Ahora el servidor funciona de manera bastante estable: las interrupciones ocurren aproximadamente 1 vez en 2 meses. En caso de falla, un reinicio es suficiente para repararlo.
Gestión de documentos en confluencia
Hoy en Confluence los escritores técnicos, programadores, ingenieros electrónicos, QA trabajan juntos.
Planeamos abandonar completamente MS Word, desarrollar documentos exclusivamente en Confluence y convertirlos a DOCX y PDF. En realidad, resultó que puede prescindir del largo proceso de transferir toda la documentación existente a un nuevo formato y luego configurar plantillas en Scroll PDF / Word Exporter. Según nuestras estimaciones, nos llevaría unos seis meses hacer esto. Resultó ser mucho más fácil transferir todos los documentos desarrollados en formato MS Word a Confluence y mantenerlos allí.
Decidimos no esperar un formato maravilloso de Confluence de acuerdo con todos los requisitos del ESKD y simplemente dividimos todos los documentos de usuario condicionalmente en documentos para el "cliente estatal" y documentos para el "cliente no estatal".
El primero lo creamos en formato DOCX, lo almacenamos y lo actualizamos en Confluence. Desarrollamos este último directamente en Confluence, exportamos a PDF si es necesario.
Gracias a las macros integradas, utilizamos tecnología de fuente única en la documentación del usuario; ahora no tenemos que cambiar manualmente un parámetro en varias versiones de documentos.
El conveniente editor WYSIWYG facilita la realización de cambios en el documento terminado: las capturas de pantalla, los iconos y los elementos gráficos permanecen en su lugar.
La función de edición colaborativa le permite colaborar en un documento. Puede compartir el documento con un experto técnico directamente en Confluence y discutir sus comentarios en tiempo real, en lugar de difundir el documento sin cesar por correo.
Para trabajar fuera de la oficina, no necesita configurar el acceso remoto. Para poder trabajar desde casa, solo necesita Internet.
Confluence ofrece al usuario la interfaz familiar de la página web con la capacidad de configurar enlaces cruzados y abrir varias pestañas en el navegador para trabajar a la vez.
Ahora almacenamos todos los documentos, elementos gráficos, fotos de dispositivos, y también mantenemos una base de conocimiento sobre los productos de la compañía en un solo lugar. No es necesario pensar dónde puede estar la fuente de las imágenes o la última versión de los documentos.
Que mas quieres hacer
Actualmente estamos configurando el proceso de alineación de la página Confluence usando el plugin Comala Workflow. Sin embargo, este complemento no funciona con archivos adjuntos de MS Word. Coordinamos dichos documentos con la ayuda de los comentarios de la versión. Ahora estamos considerando opciones para configurar la aprobación automática de los archivos adjuntos DOCX. Me gustaría que el proceso de aprobación y aprobación se use simultáneamente con las páginas Confluence y los archivos adjuntos en formato DOCX.
Cuando configuremos la aprobación automática de los archivos adjuntos, intentaremos realizar una conversión rápida de MS Word a PDF. Y luego, enviando documentos a nuestro servidor de productos impresos, desde donde la compañía de impresión toma los documentos para imprimir.
Instrucciones de búsqueda repentina
Nunca logramos abandonar MS Word, pero en el proceso de encontrar un reemplazo, de repente encontramos algo más. Confluence reunió a desarrolladores de diferentes departamentos, formó la base de conocimiento de la compañía y se convirtió en el depósito de todos los documentos de la compañía, independientemente de su formato.
Nuestra empresa tiene un principio: en cualquier situación incomprensible, tome decisiones sistemáticamente. Creemos que una solución que se basa en un modelo es mejor que una basada en la opinión o intuición de expertos.
En el caso de Confluence, el modelo de Eric Rhys de The Lean Startup fue útil. En el desarrollo de productos, ayuda a pivotar, a cambiar la dirección del desarrollo del producto. Y en la tarea de encontrar un reemplazo para MS Word, pruebe una nueva herramienta más ampliamente y encuentre los beneficios relacionados.
¡Deseamos a otros escritores técnicos modelos útiles!