How to put together a Specification Document

["Toby Considine" <Toby.Considine@gmail.com>]

First, the standard templates….

http://docs.oasis-open.org/templates/

http://docs.oasis-open.org/templates/OASISSpecificationTemplateV3.2.dot

 

Looking at Other Specifications:

http://www.oasis-open.org/specs/ - and scroll down. Look at recent ones (2009).

Small tight specification:

http://docs.oasis-open.org/ws-rx/wsrmp/200702/wsrmp-1.2-spec-os.html

http://docs.oasis-open.org/ws-dd/dpws/1.1/os/wsdd-dpws-1.1-spec-os.docx

Large spec  with complex business issues

http://docs.oasis-open.org/security/xspa/v1.0/saml-xspa-1.0-os.doc

http://docs.oasis-open.org/imi/identity/v1.0/os/identity-1.0-spec-os.pdf

Spec requiring lots of definitions

http://docs.oasis-open.org/emergency/edxl-have/os/emergency_edxl_have-1.0-spec-os.pdf

 

Conformance

Formal Conformance Requirements

http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html

TAB Guidance

http://wiki.oasis-open.org/tab/TestabilityGuide

http://wiki.oasis-open.org/tab/InteropGuide

 

RFC 2119 (how to say SHOULD and MAY)

http://www.ietf.org/rfc/rfc2119.txt

 

 

Are they white papers, or are they case studies…

http://www.oasis-open.org/casestudies/guidelines.php

 

 

Dealing with changes in Scope

2.11 TC Charter Clarification

A TC may clarify its Charter only for the purpose of removing ambiguity or for narrowing the scope of the topic defined by the Charter. The TC may not broaden or otherwise change its scope of the topic of work. The list of deliverables may be expanded only if the new deliverables are within the scope of the topic.

Approval for clarification shall require a Special Majority Vote of the TC. The clarification of the Charter may occur no earlier than the first meeting of the TC. The TC Chair shall notify the TC Administrator that a motion has been made to clarify the Charter, and the TC Administrator shall set up and conduct the ballot.

 

 

 

---

"Energy and persistence conquer all things." -- Benjamin Franklin

---

Toby Considine TC9, Inc Chair, OASIS oBIX Technical Committee OASIS Technical Advisory Board

Email: Toby.Considine@gmail.com Phone: (919)619-2104 http://www.oasis-open.org blog: www.NewDaedalus.com