oXygen XML Schema Documentation as DITA files?

[mhGLEIF]

Hello dear oXygen users and oXygen staff,

I manage a lot of XML schema documentation, and my current publication workflow is

1. Write schema & annotations in oXygen
2. Export using oXygen schema docs generator, oXygen diagrams saved manually for specific parts, plus some homebrewed XSLTs, e.g. to create lists of possible elements, tables showing all elements, cardinalities, types, descriptions, etc.
3. Load HTML doc into Word and clean up artifacts and rogue formatting with a standard Word template.
4. Export Word docs as PDFs.

As you can guess this is a lot of work, although the results are definitely worth it and oXygen takes a lot of the trouble out of each step.

I've just started testing out the DITA support and it is excellent!

Have you thought about producing an alternative DITA workflow for XML schema docs? Combined with the DITA Word plugin it would then make my workflow seamless and I imagine a lot of people have schemas to maintain and document?

I would be very excited about joining a user group for this as it's one of my main focuses and I have a lot of clear use cases, sample XSLTs etc.

[Radu]

Hi Michael,

We've had in the past several other requests to also allow exporting XML Schema documentation directly to the DITA format. I will add your vote on the internal issue we have opened for this. Right now you can generate Docbook from the XML Schema documentation and after this you can open the generated Docbook file and convert it to DITA using the predefined transformation scenario we made available for this. But this might need some manual adjustments.

Regards,
Radu

[mhGLEIF]

Hi Michael,

We've had in the past several other requests to also allow exporting XML Schema documentation directly to the DITA format. I will add your vote on the internal issue we have opened for this. Right now you can generate Docbook from the XML Schema documentation and after this you can open the generated Docbook file and convert it to DITA using the predefined transformation scenario we made available for this. But this might need some manual adjustments.

Regards,
Radu

Hello Radu,

many thanks for this hint. I tried out the conversion workflow you suggested. It's unfortunately not practical because DITA content needs to be in multiple separate files to be useful. If we could get DocBook and/or DITA output per element, datatype, annotation etc. this would be extremely helpful in generating a whole batch of reusable chunks in one click.

[Radu]

Hi Michael,

I agree that the DITA representation of the documentation would need to be split in multiple topics.
If at some point we add support to generate XML Schema docs directly to DITA I will update this forum thread.

Regards,
Radu

[mhGLEIF]

Just as a final thought on this topic:

XML schemas contain a bunch of very well-defined, standardized bits of info per element/attribute/type.

As I have dug more into DITA I noticed that an XML schema plugin would definitely work for this use case, e.g. generating instances as code snipppets, and structuring them into a map using

Code: Select all

conref

and

Code: Select all

keys

etc.

[Radu]

Hi Michael,

As it happens, we are just working on the XML Schema to DITA conversion. It will probably be available in Oxygen 19 (April-May this year).
So what we are doing is that from the conversion we produce a DITA Map. For each top level XML Schema element or other (complex type) we create a DITA Topic. For each local element we create a topic inside the parent DITA topic.
So for example someone can refer to our DITA Map in their master DITA Map and include the entire documentation or they can refer to individual topics.
If you are interested in testing what we are working on you can contact us (support@oxygenxml.com), tell us your used operating system and I can try to build a beta kit for you.

Regards,
Radu

[mhGLEIF]

Hi Michael,

As it happens, we are just working on the XML Schema to DITA conversion. It will probably be available in Oxygen 19 (April-May this year).
So what we are doing is that from the conversion we produce a DITA Map. For each top level XML Schema element or other (complex type) we create a DITA Topic. For each local element we create a topic inside the parent DITA topic.
So for example someone can refer to our DITA Map in their master DITA Map and include the entire documentation or they can refer to individual topics.
If you are interested in testing what we are working on you can contact us (support@oxygenxml.com), tell us your used operating system and I can try to build a beta kit for you.

Regards,
Radu

Thanks Radu,

that is really great news, I'm looking forward to testing it.

I'm in no great hurry, so I'm willing to wait but very happy to look at a beta if it provides value for oXygen.

Best wishes

Michael

[Radu]

Hi,

Just to update this thread, Oxygen 19.0 which we just released has support for generating XML Schema docs in DITA format.

Regards,
Radu