Re: oXygen XML editor for XSDs and (potentially) tech doc formats: Mac or Win?

Subject: Re: oXygen XML editor for XSDs and (potentially) tech doc formats: Mac or Win?
From: Alan Houser <arh -at- groupwellesley -dot- com>
To: Michael Hopwood <Michael -dot- Hopwood -at- Gleif -dot- org>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 26 Jul 2016 12:28:56 -0400

Hi Michael,

Let's see if I can go 2 for 2 ...

It's been a while since I've used it, but check out oXygen's schema documentation generator: "Tools>Generate Documentation>Generate Schema Documentation." The online help for the tool is pretty good.

I would generally favor the schema "annotation" and "documentation" elements over free-form XML comments for what you're doing.

HTH!

-Alan

Alan Houser
Group Wellesley, Inc.
Consultant and Trainer, Technical Publishing
arh on Twitter
412-450-0532

On 7/26/16 11:45 AM, Michael Hopwood wrote:

Hello Alan, colleagues,

firstly thanks to Alan for this excellent feedback â I am now looking at a (valid) draft XML schema writing with oXygen in record time.

My follow-up question is for the whole list, because itâs not necessarily specific to oXygen:

Before I reinvent any wheels, could anyone share some best practice of single-sourcing the XML schema documentation?

Status quo is a lot of freehand <! - - comments - - >in the XML schema itself. Not very reusable or easy to keep updated.

Iâm planning on going through them all to at least chunk them down into e.g.

- element name
- cardinality
- content specification/datatype
- business rules beyond schema validation

The idea is to then update the comments simultaneously to changes to the schema content, and export the XML comments into some text format before editing and applying formatting for review. There will be a few cycles of this at least.

But are there some good tips and tricks, maybe using oXygen, maybe generally part of XML, like using <annotation> or some XSLT someone might know of (I found a lot of dead links while searching for that).

Iâm afraid I need something pretty simple, like dumping a table of extracted comments for use in Word - learning DocBook etc. will have to wait til next year once the schemaâs in use and stable.

Best wishes,

Michael
Technical Writer, GLEIF


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives

Follow-Ups:

References:
oXygen XML editor for XSDs and (potentially) tech doc formats: Mac or Win?: From: Michael Hopwood
Re: oXygen XML editor for XSDs and (potentially) tech doc formats: Mac or Win?: From: Alan Houser
Re: oXygen XML editor for XSDs and (potentially) tech doc formats: Mac or Win?: From: Michael Hopwood

Previous by Author: Re: oXygen XML editor for XSDs and (potentially) tech doc formats: Mac or Win?
Next by Author: Re: Programming Term?
Previous by Thread: Re: oXygen XML editor for XSDs and (potentially) tech doc formats: Mac or Win?
Next by Thread: Re: oXygen XML editor for XSDs and (potentially) tech doc formats: Mac or Win?


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads