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

[Michael Hopwood <Michael -dot- Hopwood -at- Gleif -dot- org>]

Hi Alan,

Correct.

I got the schema docsâ content and formatting looking maybe 60-80% just using

- annotation/documentation elements (for single-sourcing goodness) and
- a little bit of HTML (plenty to enable a minimum semantics as I mentioned below and even a nested list suitable for exporting to shiny Word docs for review)

I would say you got your 2 for 2, Sir!

Best wishes,

Michael

On 7/26/16, 6:28 PM, "Alan Houser" <arh -at- groupwellesley -dot- com> wrote:

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