A centralized approach to the efficient documentation of XML schemas and business rules
Just like the processes they enable, XML schemas used for transaction messages are complex constructs. The formats need to robustly accommodate a wide range of highly specific data, while at the same time providing flexibility to adjust to every application’s needs.
Business rules set clear requirements for every attribute: is a field optional, does its use require the addition of another element and what are the allowed content formats, possibly in dependence on other fields’ values. To rationalize the maintenance and documentation of XML business rules, a centralized management approach can help to making life easier for authors and readers alike.
Sets of business rules are commonly documented in complex spreadsheets or heavy-weight PDF documents. In addition to their contents’ often overwhelming complexity, the duty of maintaining documentation creates challenges aplenty in itself: besides the need to ensure that it constantly reflects every aspect of the latest implementation, the changes from and differences between earlier implementations need to be documented as well. Various people may be involved in changing the rules and the readers’ needs differ widely depending on their task at hand.
related to the management of software documentation.
For the reader, difficult access to documentation slows down work during implementation when time is used to browse and interpret implementation documents rather than getting tasks done.
Juggling Excel sheets consumes valuable time
Message Implementation Guidelines (MIGs) are published as text documents or spreadsheets. They are static documents constructed to present complex information in an accessible way. Yet, as software documentation is commonly designed from the perspective of its creator, static documentation will even with the most user-centric mindset require that readers adapt the mental model applied by the author. Documents with a fixed structure also easily hide the relevant piece of information in a wide body of text when used as a reference.
On the other hand, ensuring that specification documents are always up-to-date, maintaining change logs, and avoiding editing conflicts can quickly grow into a major source of errors and wasted time for the authors. As interface-relevant code is being changed, more than one individual may be in charge of updating the instructions. With several analysts editing the documentation, version management unavoidably poses challenges: how to avoid conflicts and how to enable several users to edit the same document simultaneously.
In order to streamline developers’ work with MIGs on both ends, there are two obvious core areas of improvement: automating the creation of documentation and creating interactive interfaces for the reader.
Automated generation of documentation
In many fields of software development, documentation is already being created from information directly derived from the code itself. In the case of XML, in itself a descriptive markup format, this can be done to a high degree: XML message structures are defined by creating XSD files (XML Schema Definition), which are XML themselves. In contrast to the rarely changing schema, business rules are created directly in production systems – these are the parts that require separate documentation.
If the documentation of transaction rules is managed and maintained in a multi-user system, the amount of users working on the specification does no longer play a role, as there is always only one centrally stored version – developers only change the aspects they are currently working on without touching the document as a whole. Even the documentation of changes and the maintenance of documentation for older or future versions turn from a chore into a matter of course.
multi-user editing environment but most importantly enables automated documentation.
Interactive output for tailored access
Deriving documentation information directly from centrally stored information enables its presentation in a range of formats: the documentation user interface in an automated environment is not a static document, but a set of rules translating the specifications into human-readable representations.
Automated documentation interfaces can at the same time provide interactive means of browsing through the specifications and, for instance, allow printing out formal implementation guides. The end user decides what aspects of the specification are of relevance to them and selects the structure and contents of the MIG themselves.
several output formats can be provided with no extra effort. It also enables creating
change logs and other algorithmic documentation formats on the fly.
Furthermore, automatically created documentation based on a centralized business rule database always reflects the latest version and any problems with documentation lagging behind are avoided. For the user, it is easy to compare versions, even visualizing changes between them, as they can be analyzed in real-time.
Towards fully integrated XML schema management
Schema-based XML and the related business rules are a most suitable candidate for automated generation of documentation. Not only does maintaining XSD and rules in a central database system eliminate all worries about versioning conflicts or multiple editors, but it at the same time allows to translate the definitions into human-readable formats using smart algorithms and user-friendly interfaces.
In the long run, the most efficient workflow is to use one centralized XML management tool that bundles the maintenance of schemas themselves along with their automated documentation. Platforms like XMLdation’s myXML further allow integrating the same logic that already makes the XSD human-readable to test message files in validation software.