Cinco razões principais para documentar os seus esquemas

O desenvolvimento de esquemas é frequentemente um processo iterativo, e os desenvolvedores geralmente não começam do zero. Os esquemas XML, e, cada vez mais, os esquemas JSON, são construídos a partir de documentos existentes ou herdados de outras equipas. A capacidade de compreender como os componentes do esquema se relacionam e de analisar as notas sobre as decisões de desenvolvimento é extremamente útil, mas muitas vezes impossível devido à falta de documentação adequada.

Vamos analisar algumas das razões pelas quais a documentação deve ser uma parte integrante do desenvolvimento dos seus esquemas XSD, JSON ou de outros formatos.

Benefícios da documentação do esquema XSD

Aqui estão as principais razões pelas quais não deve ignorar a etapa de documentação para o seu próximo esquema.

1. Permite uma comunicação fácil entre os membros da equipa de desenvolvimento.

O desenvolvimento de esquemas é frequentemente um processo colaborativo, e uma documentação clara e concisa ajuda a evitar confusões e a aumentar a produtividade, uma vez que diferentes programadores trabalham em diferentes aspetos de um esquema ou de um conjunto de esquemas. A revisão por pares é outro processo facilitado por uma documentação clara, permitindo que vários especialistas avaliem o modelo de conteúdo.

2. Permite a rápida integração de projetos herdados.

Isto está intimamente relacionado com o ponto anterior. O código proveniente de uma empresa adquirida ou de um departamento que passou por uma transição sempre se beneficia de documentação. Mesmo que o projeto tenha sido desenvolvido na sua organização, o programador original pode já não estar disponível, ou talvez o desenvolvimento tenha sido dividido em partes e nenhuma pessoa individualmente conhece todo o projeto.

Naturalmente, poucos projetos são compostos apenas por esquemas. Para uma análise completa do código existente, é útil gerar diagramas UML para documentar e visualizar facilmente o projeto.

3. Centraliza informações sobre esquemas importados ou incluídos.

Em vez de analisar inúmeros documentos para determinar as relações existentes, a documentação de esquemas pode incluir informações sobre todos os documentos relacionados num único local centralizado.

4. Permite que utilizadores sem conhecimentos técnicos compreendam e analisem as definições de esquemas

Como a documentação do esquema é legível por humanos, ela permite a colaboração com uma vasta gama de especialistas em diversas áreas, que podem compreender e contribuir durante o desenvolvimento e a evolução do esquema.

5. As ferramentas automatizadas tornam tudo mais fácil.

Realmente, não há desculpa para não documentar os seus esquemas, especialmente quando o software torna o processo tão simples. Vamos analisar como pode fazê-lo com uma ferramenta como o XMLSpy.

O XMLSpy oferece documentação de esquemas totalmente personalizável, mas ao mesmo tempo completa, para esquemas XSD, esquemas JSON e taxonomias XBRL. Vamos analisar como funciona.

Gerar documentação para o esquema XML

O editor XML XMLSpy oferece geração automática de documentação para esquemas XML, esquemas JSON, taxonomias XBRL e até mesmo definições WSDL, e o processo é semelhante para cada um. Com o documento do esquema aberto, selecione "Gerar Documentação" no menu "Design do Esquema".

Tem a opção de utilizar o modelo de documentação integrado, ou, se tiver o Altova StyleVision instalado, pode criar o seu próprio modelo com o nível de personalização que necessitar. Em seguida, escolha se pretende gerar a documentação em HTML, Word, RTF ou PDF. (Nota: A geração de documentos PDF requer que o StyleVision esteja instalado na mesma máquina.)

Outras opções permitem definir como as imagens são processadas, e, finalmente, exatamente quais componentes e detalhes são documentados. Vamos analisar a documentação gerada para um ficheiro XSD, e depois mostrarei as diversas opções para documentar esquemas JSON e XBRL.

Aqui está um excerto da documentação HTML para o esquema XSD de Relatório de Despesas, incluído no projeto de exemplos do XMLSpy.

Os componentes do esquema são apresentados graficamente, juntamente com o código-fonte correspondente, e os hiperligações facilitam a referência cruzada de detalhes de elementos, atributos e tipos relacionados.

As características e os aspetos relevantes são apresentados de forma clara, permitindo uma análise imediata.

Quando componentes de outros esquemas são incluídos, esses esquemas também são documentados.

Gerar documentação em formato JSON Schema

A crescente utilização do JSON Schema para aplicar validação de dados a fluxos JSON sublinha a importância da documentação para este tipo de esquema.

As opções de geração de documentação para JSON Schema são semelhantes às do XSD, mas, naturalmente, específicas para JSON, com opções para incluir detalhes sobre propriedades, arrays, padrões, e assim por diante.

Documentação da Taxonomia XBRL

Agora chegamos às taxonomias XBRL, que são alguns dos esquemas mais complexos existentes. A documentação aqui não é útil apenas para os desenvolvedores das taxonomias, mas também para os intervenientes não técnicos do XBRL, como contadores e outros profissionais da área financeira.

No menu XBRL do Editor de Taxonomia XBRL, o comando "Gerar Documentação" oferece as opções habituais, desta vez específicas para componentes XBRL, como rótulos e bases de ligação.

Seja qual for o esquema que esteja a utilizar – XSD, JSON ou XBRL – os benefícios da geração de documentação para visualizar, compreender e comunicar a estrutura e as relações do esquema são numerosos. Além disso, o facto de poder gerar automaticamente a documentação no XMLSpy em poucos segundos elimina qualquer obstáculo para a realização do trabalho.

Se ainda não é cliente, pode experimentar o XMLSpy gratuitamente durante 30 dias.