[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

Re: Common documentation standard across multiple XML schemas

• From: "G. Ken Holman" <gkholman@CraneSoftwrights.com>
• To: "xml-dev@lists.xml.org" <xml-dev@lists.xml.org>
• Date: Thu, 16 May 2013 08:19:38 -0500

At 2013-05-16 10:36 +0100, Lech Rzedzicki wrote:
>Thank you Ken - this is looking really good and not sure how how I 
>missed it - I will definitely give it a go.
>May I suggest that you rephrase some of your description on 
><http://cranesoftwrights.com/resources/#xslstyle>http://CraneSoftwrights.com/resources/#xslstyle 
>so that search engines pick up on "XSL documentation" keywords - in 
>spite of being very relevant, your page doesn't show up in top Google results.

Thank you!  I have just tweaked the wording to see if this helps.

>Just curious, have you used this markup for anything other than XSL?

No, as I haven't yet had the need.

>In general do you think that this is a good idea? Like I said I have 
>some reservations due to the fact that you're documenting different 
>concepts in Schemas and in XSL...

Forgive me for giving you the impression the XSLStyle scaffolding 
itself would be good for XSD ... I was simply trying to convey the 
architectural decision I made of standardizing a documentation 
scaffolding but not constraining the user's choice of vocabulary 
within the documentation.

One private flavour of XSLStyle stylesheets was used for US 
intelligence stylesheet documentation:  the stylesheets were 
formatting the vocabulary to produce PDF and HTML of intelligence 
documents, and I used the vocabulary itself to document the 
vocabulary's stylesheets.  This meant there was a recursive 
invocation of the stylesheets to produce the HTML documentation of themselves.

The other developers didn't need to learn DocBook ... they already 
knew the vocabulary we were working with.  The scaffolding approach 
turned out to be amazingly adaptable.

So it was just the approach I was trying to share with you should you 
find that it helps meet your needs.

. . . . . . . Ken

--
Contact us for world-wide XML consulting and instructor-led training |
Free 5-hour lecture: http://www.CraneSoftwrights.com/links/udemy.htm |
Crane Softwrights Ltd.            http://www.CraneSoftwrights.com/x/ |
G. Ken Holman                   mailto:gkholman@CraneSoftwrights.com |
Google+ profile: https://plus.google.com/116832879756988317389/about |
Legal business disclaimers:    http://www.CraneSoftwrights.com/legal |

• References:
  • Common documentation standard across multiple XML schemas
    • From: Lech Rzedzicki <xchaotic@gmail.com>
  • Re: Common documentation standard across multiple XML schemas
    • From: "G. Ken Holman" <gkholman@CraneSoftwrights.com>
  • Re: Common documentation standard across multiple XML schemas
    • From: Lech Rzedzicki <xchaotic@gmail.com>