Groups - Alternate Specification Proposal Illustration (oasis-sdd-spec-draft-AltIllustration-Clean.doc) uploaded

[bamiller@us.ibm.com]

After the October F2F, I was thinking (a lot) about this item from the
meeting minutes:

"Need to look at structure of specification: overview/primer (separate
document or intro to specification?), pictures, normative vs. non-normative
content and where it goes, examples, etc."

I went and looked at quite a few OASIS specifications (of all different
sorts) to identify what I considered to be good practices. I started to
write down various suggestions for things we might consider for the SDD
spec, then I realized that trying to describe these things out of context
wasn't all that useful.

So I started to just record the ideas in the spec itself. The result is
posted in "Working documents", and I would like the TC's feedback.

Here's a description of some of the noteworthy items:
- Updated introductory material to include several sections that I found in
other specs that I thought were useful (terminology, requirements,
objectives, motivations)
- Added a "concepts" chapter that is intended to describe the "big picture"
for SDD. It's only an illustrative skeleton at this point.
- For the main body that explains all the schema properties, I added
pictures (these, too, are illustrative only...I recognize their
deficiencies and am not suggesting this is the real depiction) and tables
that summarize the properties. The explanatory text then gives the details.
I also added schema snippets in-line in these sections. 
- Moved the "common" types and "groups" into the chapter where they're
first introduced. 

I did the last two things only for the PackageDescriptor chapter, to
illustrate the ideas (doing this for the DeploymentDescriptor chapter would
be a much larger job).

- Added placeholders for chapters that I suspect we'll want to include. I'm
sure I've forgotten some.
- General terminology updates, especially around an item I
discovered/observed about SDD being composed of PD & DD (rather than
composed of "SPD" and "SDD", to remove ambiguity of "SDD" term). This
includes updates to the abstract and throughout other places.

Caveats:
- This reflects my personal preferences about how I like to consume a
specification. I'm not claiming it's "right", but it is based on reviewing
quite a few other specifications.
- The point of this example is to illustrate structure and content. I am
certain that the content does not entirely match the latest schema
(although I made some efforts to include some things resolved at the F2F
just to improve the illustration), and I am certain that many errors exist.
I'm not looking for feedback on complete correctness and gory details, but
rather thoughts about general structure/content organization and
consumability. Again, this is illustrative only. 

I started with the intent of showing marked-up revisions but it got too
messy, so I dispensed with that.

If some or all of this structure and content is deemed useful, then we
could embark on an initiative to update the overall spec in this fashion,
with real correct content and real pictures, etc. I know that that would be
a non-trivial job (there's an understatement), but perhaps we can
collaborate or enlist additional help and I think that could go on mostly
in parallel with the usual kinds of spec content updates (technical items).


This is my first attempt at responding to what I heard at the F2F and based
on reviewing other specifications to identify what I think are
consumability improvements. It is not an assertion that I've hit the
mark...that's what I'm seeking input about.

Anyway, please let me know what you think, and be blunt. 

E-mail discussion is fine, and I'll also put this on a TC call agenda.

Thanks.



 -- Mr Brent Miller

The document named Alternate Specification Proposal Illustration
(oasis-sdd-spec-draft-AltIllustration-Clean.doc) has been submitted by Mr
Brent Miller to the OASIS Solution Deployment Descriptor (SDD) TC document
repository.

Document Description:
Some specification restructuring/reformatting was suggested at the October
F2F meeting. This is an illustrative proposal toward that end. It is for
discussion and iteration.

View Document Details:
http://www.oasis-open.org/apps/org/workgroup/sdd/document.php?document_id=21347

Download Document:  
http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/21347/oasis-sdd-spec-draft-AltIllustration-Clean.doc


PLEASE NOTE:  If the above links do not work for you, your email application
may be breaking the link into two pieces.  You may be able to copy and paste
the entire link address into the address field of your web browser.

-OASIS Open Administration