energyinterop — archive

How to put together a Specification Document

From: Toby Considine
To: [email protected]
Date: Wed, 09 Dec 2009 19:33:00 -0000














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: [email protected]

  Phone: (919)619-2104
  http://www.oasis-open.org 
  blog: www.NewDaedalus.com