Las cinco razones principales para documentar sus esquemas
El desarrollo de esquemas suele ser un proceso iterativo, y los desarrolladores normalmente no comienzan desde cero. Los esquemas XML, y cada vez más, los esquemas JSON, se construyen a partir de documentos existentes o se heredan de otros equipos. La capacidad de comprender cómo se relacionan los componentes de un esquema y analizar las notas sobre las decisiones de desarrollo es de gran ayuda, pero a menudo es imposible debido a la falta de documentación adecuada.
Analicemos algunas de las razones por las cuales la documentación debe ser una parte integral de su desarrollo de esquemas XSD, JSON u otros.
Beneficios de la documentación del esquema XSD
Aquí están las principales razones por las que no debería omitir la fase de documentación para su próximo esquema.
1. Permite una comunicación fluida entre los miembros del equipo de desarrollo.
El desarrollo de esquemas suele ser un proceso colaborativo, y una documentación clara y concisa ayuda a evitar confusiones y aumenta la productividad, ya que diferentes desarrolladores trabajan en diferentes aspectos de un esquema o conjunto de esquemas. La revisión por pares es otro proceso que se facilita con una documentación clara, permitiendo que varios expertos evalúen el modelo de contenido.
- Permite la rápida adaptación a proyectos heredados.
Esto se relaciona directamente con el punto anterior. El código proveniente de una empresa adquirida o de un departamento que ha cambiado siempre se beneficia de la documentación. Incluso si el proyecto se originó en su organización, es posible que el desarrollador original ya no esté disponible, o quizás el desarrollo se realizó por partes y ninguna persona conoce el proyecto en su totalidad.
Por supuesto, pocos proyectos se componen únicamente de esquemas. Para un análisis completo del código existente, es útil generar diagramas UML para documentar y visualizar fácilmente el proyecto.
- Centraliza la información sobre los esquemas importados o incluidos.
En lugar de revisar numerosos documentos para determinar las relaciones que existen entre ellos, la documentación del esquema puede incluir información sobre todos los documentos relacionados en un único lugar centralizado.
- Permite que los interesados, incluso aquellos sin conocimientos técnicos, comprendan y analicen las definiciones de esquemas
Dado que la documentación del esquema es legible para los humanos, esto facilita la colaboración con una amplia gama de expertos en diferentes áreas, quienes pueden comprender y aportar ideas durante el desarrollo y la evolución del esquema.
- Las herramientas automatizadas lo facilitan.
En realidad, no hay excusa para no documentar sus esquemas, especialmente cuando el software facilita este proceso. Veamos cómo puede hacerlo utilizando una herramienta como XMLSpy.
XMLSpy ofrece documentación de esquemas completamente personalizable, pero a la vez exhaustiva, para esquemas XSD, esquemas JSON y taxonomías XBRL. Veamos cómo funciona.
Generar documentación para esquemas XML
El editor XML XMLSpy ofrece la generación automática de documentación para esquemas XML, esquemas JSON, taxonomías XBRL, e incluso definiciones WSDL, y el proceso es similar para cada uno. Con el documento del esquema abierto, seleccione "Generar documentación" en el menú "Diseño de esquema".
Tiene la opción de utilizar la plantilla de documentación integrada, o, si tiene instalado Altova StyleVision, puede diseñar su propia plantilla con el nivel de personalización que necesite. Luego, elija si desea generar la documentación en formato HTML, Word, RTF o PDF. (Nota: La generación de documentos en formato PDF requiere que StyleVision esté instalado en la misma máquina)
Otras opciones le permiten definir cómo se gestionan las imágenes, y, finalmente, exactamente qué componentes y detalles se documentan. Veamos la documentación generada para un esquema XSD, y luego le mostraré las diferentes opciones para documentar esquemas JSON y XBRL.
Aquí hay un fragmento de la documentación HTML para el esquema XSD de los informes de gastos, incluido en el proyecto de ejemplos de XMLSpy.
Los componentes del esquema se muestran gráficamente, junto con el código fuente correspondiente, y los hipervínculos facilitan la referencia cruzada de los detalles de los elementos, atributos y tipos relacionados.
Las propiedades y características se muestran de forma clara para facilitar el análisis inmediato.
Cuando se incluyen componentes de otros esquemas, estos esquemas también se documentan.
Generar documentación para esquemas JSON
La adopción continua de JSON Schema para aplicar la validación de datos a los flujos de JSON subraya la importancia de la documentación para este tipo de esquema.
Las opciones para generar la documentación de esquemas JSON son similares a las de XSD, pero, por supuesto, específicas para JSON, e incluyen opciones para incluir detalles sobre propiedades, arreglos, patrones, etc.
Documentación de la taxonomía XBRL
Ahora llegamos a las taxonomías XBRL, que son algunos de los esquemas más complejos que existen. La documentación aquí no solo es útil para los desarrolladores de taxonomías, sino también para los interesados en XBRL que no son técnicos, como contadores y otros profesionales del ámbito financiero.
En el menú XBRL del Editor de Taxonomía XBRL, la opción "Generar documentación" ofrece las opciones habituales, pero en esta ocasión específicas para los componentes XBRL, como las etiquetas y las bases de datos de enlaces.
Ya sea que esté trabajando con esquemas XSD, JSON o XBRL, los beneficios de la generación de documentación para visualizar, comprender y comunicar la estructura y las relaciones de los esquemas son numerosos. Además, el hecho de que pueda generar documentación automáticamente en XMLSpy en cuestión de segundos elimina cualquier obstáculo para completar la tarea.
Si aún no es cliente, puede probar XMLSpy de forma gratuita durante 30 días.