OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

cti message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Options for organizing your specifications

Hi all, 

Having exchanged some emails on options for organizing the specs for TAXII, I thought I'd send a note to the full TC so that each group can be start thinking about how to organize their work. 

First note: OASIS has the concepts of standards-track work products (Committee Spec Draft -> Committee Spec -> OASIS Standard) and non-standards track work (Committee Notes). Standards track is the stuff people use and implement. Non-standards track is stuff that promotes, educates, etc. So a definition of data types is going to standards track. A usage guide is probably going to be non-standards track. (Of course, standards track works can have non-normative content as well - e.g. an introductory section before the spec content itself.) 

The TAXII SC asked about requesting templates for documents based on  http://taxii.mitre.org/specifications/version1.1/

There are several ways something like that can be set up. 

1. Multiple, independent work products. Each piece becomes a separate Committee Spec draft with its own title, version number and each can eventually become a Committee Specification / OASIS Standard. For a real world example, see the recent OASIS Standards for KMIP (http://docs.oasis-open.org/kmip/)

Pros: each work product can evolve separately. You can advance the HTTP Protocol Binding Specification independently of the other parts. Also, processing is easier as we go through publication and release. E.g. easier for me to release, easier for you to track comments. 
Cons: lots of moving parts. Multiple public reviews, multiple ballots and approvals. And no one "thing" named TAXII Version 1.1 (or etc.) Possibly complications keeping components synchronized across the different parts. 

2. Single work product. The pieces of documentation become chapters in a single work product. For a real world example, see DITA 1.2 (http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html). 

Pros: one individual work to deal with through all the steps. One "thing" named TAXII Version 1.1 (or etc.) Process is straight forward - one public review, one approval vote, etc. 
Cons: tends to make a big, complicated looking spec. You're probably going to need multiple editors and they're going to have to coordinate. Nothing moves independently. For example, if you want to publish an update to the schema, you are updating and processing the entire piece of work. (Which, to be honest, is more work for me than you all but still something to consider.) 

3. Single, multi-part work product. (This is what the TAXII group is doing.) The overall work is one, named "thing" but it is composed of parts that are stand-alone units in that they have their own cover page, their own Tables of contents, their own directory tree. For a real life example, see the OData V4.0 (http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html - look at the Associated artifacts listing on the cover page to see all the parts). 

Pros: one individual work to deal with through all the steps - approvals, public reviews, etc. One "thing" named TAXII Version 1.1 (or etc.). However, also the ability to decompose content into logical units that users might want to read and work on independently. E.g. the HTTP Protocol Binding Specification is basically there as a stand-alone unit. Possibly easier coordination for editors - e.g. each part could have its own editor. 
Cons: More complicated to organize in advance. Keeping track of comments *could* become more complicated. Handling things like cross-references can be more complex to manage. Again, everything evolves as a unit. E.g. to update HTTP Protocol, the entire unit must move up through the process. Candidly much of the burden falls on TC Admin once we have you organized and going. Time will generally be spent on your first release and public reviewing debugging issues across the content. But the benefit of having addressable parts often makes it worth doing this way. 

Anyway, just wanted to plant those seeds. I'm setting up your SC sites right now and should have them for you this afternoon. 

Let me know if you have any questions. 

Chet Ensign
Director of Standards Development and TC Administration 
OASIS: Advancing open standards for the information society

Primary: +1 973-996-2298
Mobile: +1 201-341-1393 

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]