AKOMA NTOSO Documentation
PLEASE NOTE this documentation is still work in progress so bear with us. Please give us your comments so that we can improve it further.
In the documentation you will be able to find the semantic meaning of AKOMA NTOSO elements and attributes and also the technical explanation of the characteristics and requirements of each element and attribute.
The AKOMA NTOSO documentation can be browsed using different
perspectives to provide the readers with the navigation and
explanations that best fit their different expertise and information
needs.
The semantical documentation is intended as an aid to the drafters/clerks who are in charge of marking up parliamentary, legislative and judiciary documents to translate them to the AKOMA NTOSO format. In the semantic documentation the structural and semantic parts as well as the metadata of the different documents currently supported by AKOMA NTOSO are presented and explained. For each typology of document (document type) for each component of the schema is described by:
- purpose;
- use cases;
- correct examples;
- incorrect examples;
- a set of external/internal references that can be read in order to understand the best way to use an AKOMA NTOSO structure in the legal context.
Currently the semantic documentation cover the following document types:
The technical documentation is intended for the "tool makers/programmers" who are in charge of development of tools and applications used to process AKOMA NTOSO documents. In the technical documentation you will find, for each schema's structure, wherever it is meaningful, the following items:
- description of the XML pattern that the structure belongs to;
- description of the structure itself;
- the context of the structure;
- a collection of valid examples;
- a collection of invalid examples;
- a set of external/internal references.
In order to better meet the different needs of users we provide access at the technical documentation through three indexes, that are meant to meet defferent needs. So the very same technical documentation can be accessed by:
- Schema Definitions - In this index, the structures of the schema are grouped by the classes of the XSD schemas (attributes groups, elements groups, simple types, complex types, elements and attributes).
- Patterns Categories - In this index, the structures of the schema are grouped by the XML pattern that each of them belongs to.
- Alphabetical Listing - In this index the elements of the technical documentation are listed alphabetically
We have also working to develop a "Quick References" document to provide a short explanation of all AKOMA NTOSO elements to be used as references.
We have also began to build Examples of AKOMA NTOSO documents (best viewed with Firefox, Opera or Safari - they can be viewed with IE too but performance will be slow). They are presented in a way that allows the user to click on any element and see the part of the text it refers to if any; the technical or semantic documentation of the selected element are displayed in separate tabs; tags in the metadata part of the schema will lead directly to the technical documentation of that element. You can also select what level of display you want to see the XML code thus allowing quick movement around the schema. It is also possible to click on the text at the right end side of the screen (HTML Representation) and see highlighted in the left part of the screen the corresponding XML code.
A non technical user, browsing through the examples, will be able to better appreciate what is under the "bonnet" and see what is meant by mark-up and also better understand its potential. Please note that a drafter/clerk will never come across the actual XML and the mark-up will be done by using the traditional interface of a text editor with forms etc. So, no need to "panic".
A technical user will be able to better understand elements, their requirements etc. in the context of actual examples while at the same time accessing the technical and semantical documentation if needed.
Please feel free to provide us with your inputs and suggestions which will be very much appreciated.
