Page 1 of 1

oXygen XML Schema Documentation as DITA files?

Posted: Fri Dec 30, 2016 2:54 pm
by 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.

Re: oXygen XML Schema Documentation as DITA files?

Posted: Tue Jan 03, 2017 4:53 pm
by 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

Re: oXygen XML Schema Documentation as DITA files?

Posted: Fri Jan 06, 2017 11:32 am
by mhGLEIF
Radu wrote: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.

Re: oXygen XML Schema Documentation as DITA files?

Posted: Fri Jan 06, 2017 12:22 pm
by 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

Re: oXygen XML Schema Documentation as DITA files?

Posted: Thu Feb 23, 2017 5:31 pm
by 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.

Re: oXygen XML Schema Documentation as DITA files?

Posted: Fri Feb 24, 2017 11:00 am
by 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

Re: oXygen XML Schema Documentation as DITA files?

Posted: Tue Feb 28, 2017 12:17 pm
by mhGLEIF
Radu wrote: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

Re: oXygen XML Schema Documentation as DITA files?

Posted: Thu Apr 06, 2017 1:25 pm
by 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