Hace unos meses, completé una de las etapas de mi trayectoria profesional de Shiva multibrazos en una startup para desarrollar un sistema de gestión de laboratorio de pruebas no destructivas. Le diré cómo pude documentar la parte del desarrollo relacionada con la conexión y la generación de documentos en un volumen suficiente para el uso silencioso del sistema creado durante dos años.
Intentaré proporcionar al lector material útil tanto como sea posible, y al mismo tiempo observar los intereses del proyecto y no revelar los matices de la implementación y el uso interno.
Dado:
- Genial equipo de desarrollo y, por supuesto, el director del proyecto. En el momento del inicio del proyecto, trabajé como director de arte en uno de los estudios de Tomsk, luego terminé en el equipo de inicio
- puesta en marcha con fechas de hormigón armado para un evento específico : inicio de aceleración en el FRII
- conjunto inicial de plantillas de más de 15 documentos de varios tamaños de 1 página a más de 100 páginas en un documento con diferentes condiciones de conexión
- proyecto de terceros que debe integrarse con una solución futura
- diseñador (analista, diseñador, diseñador, director de arte, propietario de producto, gerente de producto, todo en uno)
Desafío:
- lanzar un proyecto a tiempo
- No muera el equipo seis meses después en el caos al conectar nuevas funciones e incluso más documentación en el sistema (en caso de completar con éxito la aceleración)
- con el mínimo número de letras y los esfuerzos realizados para lograr la documentación adecuada
- enajenación de documentación a cualquier equipo / empleado que no esté en contexto
Debo decir de inmediato que las siguientes plantillas de documentos se hicieron sin ninguna metodología, me guié exclusivamente por los detalles del proyecto, el sentido común y un límite de tiempo terrible.
Análisis y preparación.
Espero que comience cualquier tarea no trivial con el análisis del material, en mi caso, el material eran plantillas de documentos y un proyecto existente con el que se necesitaba la integración. Pero entonces solo estamos hablando de documentos. Necesitaba determinar la frecuencia de usar el mismo tipo de datos dentro del mismo documento y entre documentos. Era necesario comprender si se necesita un sistema en este momento o si puede hacerlo rápidamente en la rodilla primero y luego lidiar con el resultado. En ese momento, se decidió que el sistema era necesario, ya que casi todos los datos, en un volumen u otro, se repetían dentro de un documento y en todo el paquete de documentos, y esto es una señal segura de confusión ya en el segundo o tercer documento al conectarse.
El siguiente paso es comprender el estado de limpieza del marcado de documentos. Te lo explicaré. El hecho es que recibí plantillas de documentos ya completadas del metodólogo: quién, cuándo y cómo hice estos documentos no lo sabía, incluso si supiera que esto hubiera dado poco. El documento .docx en el interior es algo así como xml para texto y algunos elementos pueden no ser visibles visualmente en un documento abierto, pero pueden estar presentes en el marcado del documento. Se desconoce cómo reaccionará el generador de documentos y varios software para ver el documento a estos elementos de marcado. La apuesta principal fue en Microsoft Word, pero hay OpenOffice, LibreOffice y todos pueden dar resultados diferentes. Por lo tanto, todas las plantillas primero pasaron por el procedimiento de limpieza de estilos: un restablecimiento completo de cualquier diseño y rediseño con estilos de documento, en algún lugar con el ajuste de la estructura del documento. E incluso después de este procedimiento, recopilamos problemas en el contenido de los documentos después de la generación. En el futuro, llegué a la conclusión de que si el documento es pequeño, es mejor volver a clasificarlo desde cero y no llevar la plantilla proporcionada por el metodólogo al trabajo, esto ahorra tiempo en documentos de hasta 5 páginas. Nadie quiere buscar la razón por la cual algo salió, el proceso de depuración de estos casos es extremadamente tedioso para el equipo. En la misma etapa, si tiene un paquete de documentos, llega a un lenguaje visual uniforme.
Y dado que realizamos un rito de limpieza de documentos, el huevo de pascua en la metainformación se sugirió, porque a la gente le gusta compartir buenos documentos
Después de todo el trabajo relacionado con la preparación de documentos, procedí a marcar documentos para la generación automática.
Marcado de documentos
En esta etapa, solicite a los desarrolladores el formato variable que admita el generador de documentos seleccionado por su equipo para que no tenga que rehacerlo más tarde. Tuve que rehacerlo, pero esto se debió al reemplazo del generador. El nuevo generador no podía funcionar con las variables en el formato anterior, pero las capacidades del nuevo generador resultaron ser más importantes para nosotros y decidimos reemplazarlo.
Verifique la suficiencia de información en el sistema, determine cuántos datos no son suficientes para el documento. ¿Cuándo se supone que estos datos aparecerán en el sistema? Si no hay suficientes datos para la autosuficiencia del documento, es mejor posponerlo. ¿Qué es la autosuficiencia de documentos? En mi caso, había un documento que completamos en 3 etapas, pero era autosuficiente de inmediato para un escenario específico, pero no cubría el resto de los escenarios, por lo que decidimos extender el documento para la venta, dejando celdas en blanco para que el usuario complete los escenarios descubiertos, y posteriormente terminó el documento con la apariencia de la funcionalidad necesaria.
Documentación de variables e interfaces
Al comienzo de la nota, escribí que estábamos estrictamente limitados a un evento específico. Además de eso, ya tenía planeado unas vacaciones. Cuando no estaba disponible, pero necesitaba con urgencia agregar una variable del sistema (no disponible en la interfaz de usuario final), los desarrolladores agregaron la línea con la variable ellos mismos, y luego agregué las condiciones faltantes. En este sentido, la especificación de variables no pretende ser correcta e ideal, pero es un documento de trabajo bastante, que posteriormente se expandió y evolucionó. La pestaña principal en el documento no cambió estructuralmente desde el principio y en el momento de mi partida del proyecto.
Plantilla "
Especificaciones para estos campos ", que puede tomar y usar en su trabajo. En el documento, dejé parte de los datos como ejemplo. Esta plantilla puede ser adecuada para la documentación de la interfaz para controlar la calidad del desarrollo. Por ejemplo, el propietario de un producto sabe qué resultado mínimo obtendrá, el desarrollador comprende claramente qué mínimo se debe obtener a partir de la descripción de la tarea + especificaciones de estos campos, y si falta algo, lo informará, el ingeniero de pruebas claramente ve casos obvios. Al final, todo está en negro.
Al principio, el documento tomará una cantidad significativa de horas, pero luego le ahorrará mucho tiempo, y la actualización ocasionalmente tomará literalmente minutos.
Contenido:
- La página es una guía para una persona fuera del contexto del proyecto, dónde buscar. Útil para un nuevo miembro en un equipo o para subcontratar un proyecto.
- Nombre del campo
- Tipo de campo
- Campo obligatorio en los proyectos (le recuerdo que teníamos una base de datos de otro proyecto): un marcador para sincronizar el requisito de vinculación entre el documento y la interfaz. Si la información en el documento es vinculante y el sistema no puede recibirla de otra manera, será necesario que este campo sea obligatorio en la interfaz
- Máscara de campo: el formato para registrar la información está claramente definido en la documentación reglamentaria.
- Valor por defecto
- El número máximo de caracteres en el campo.
- Escalabilidad de campo (depende de la resolución): descripción del comportamiento de un elemento de interfaz según la resolución
- Requisito de datos: qué interacción está permitida con el elemento de interfaz y qué puede entrar
- Muestra exitosa
- Marcador de posición: información sobre herramientas para el usuario dentro del elemento de interfaz
- Personalización del campo: elementos de interfaz no estándar o tareas finalizadas
- Información adicional al lado del campo: cuando no se puede prescindir del marcador de posición debido a la cantidad de texto, usamos una información sobre herramientas o un identificador
- Tipo de validación
- Mensaje de validación: condiciones del sistema y respuesta
- Variable en plantillas de documento: lo que se insertará en la plantilla de documento
- Enlace a la página: no se utiliza al final
- Ubicación del campo en la interfaz: no se utilizó como resultado
Documentación de conexión de documentos
Para recibir el documento por el usuario final, no es suficiente editarlo y marcarlo; el documento aún necesita estar conectado correctamente. Es especialmente importante si tiene la misma plantilla, dependiendo de las condiciones, cambia su contenido. Para esto, utilicé un documento separado.
Plantilla "
Conexión de documentos ", espero que sea útil para alguien.
Contenido:
- Estado: indica el estado actual del documento en el sistema. Conectamos un documento en 3 etapas, el estado del documento era "Finalizar"
- Documento: el nombre del documento dentro del equipo, la base de conocimiento y dentro de nuestro sistema de documentación y configuración de tareas
- Tipo
- El formato del documento es cuando el mismo documento puede estar en diferentes plantillas dependiendo de la documentación reglamentaria y técnica a la que corresponde este documento
- Formación: un documento puede ser solo una plantilla en la que las variables simplemente se sustituyen o de una plantilla de 3 páginas puede obtener más de 100 documentos de página: documentos dinámicos
- La presencia en el paquete es una característica del sistema, puede obtener un paquete de documentos o descargar documentos por separado
- Condición de presencia: la presencia de un documento específico en el paquete
- La función de conexión es esa parte del documento que no está en la plantilla y está regulada por el código.
- Enlace al archivo para conectar
- Descargar por separado
- El nombre del archivo a descargar: un documento en el sistema puede llamarse como desee, pero el usuario final debe ver un nombre específico al descargar
Total
Como resultado, completé 362 líneas en ambos documentos. Volumen impresionante? Pero, de hecho, se trata de más de 30 plantillas de documentos y se gasta un total de 40-60 horas de trabajo de una persona en dos años (1-1.5 semanas), excluyendo la edición de las plantillas en sí y la redacción de las tareas de conexión.
El proyecto superó con éxito la aceleración en el IIDF y se convirtió en su propio equipo de desarrollo. Gracias a la documentación existente, los nuevos miembros del equipo no tuvieron que profundizar durante mucho tiempo en lo que se hizo antes de ellos con respecto a la generación de documentos. Todos los miembros del equipo tenían acceso al estado actual de los documentos conectados en cualquier momento.
Las principales etapas en la documentación del proceso de generación de documentos:
- Análisis del contenido de los documentos.
- Documento de higiene
- Corregir variables en paralelo con marcado de documentos
- Corrige los matices de las plantillas de documentos de conexión
Gracias por llegar al final.