-
Notifications
You must be signed in to change notification settings - Fork 10
Spec Writer Handbook
The purpose of this page is to give specification editors, authors and general TC members a guide for both the process steps to produce Standards and non-Standards track publications. This involves guidance around process steps which are mandatory for OASIS and those that are deemed as good practice. This will also outline various other needs such as considerations around tools, styles, references and the like. This does not replace any official OASIS documents and processes but intended to compliment them.
OSLC has always strived to maintain a minimalist approach to specification development, focus on a limited number of prioritized scenarios and deliver just enough specifications in support of that. Then, iterate: repeat the same process, including improvements into the process learned from the prior iteration and continue to deliver value. Doing just enough specification development, along with knowing when to take the specifications through the OASIS standardization process needs some consideration. The approach we are taking is to build smaller specifications that focus on defining a capability that can be independently adopted. That capability may have prerequisites but those should be minimized. A TC should consider wrapping a set of capabilities into a package that goes through the OASIS standardization process together. This package will have a version number associated with it for ease of identifying the package and talking about it, it does not imply the capabilities are at such a version number that have such a major release change or incompatibility. The details of what has changed and compatibility with other revisions, will be highlighted within or in support of each package or capability.
- Determine full set of deliverables (specifications) that have an appropriate size and scope (wiki, as-needed, SpecRoadmap)
- Outline a roadmap/plan for developing the various pieces with target milestones (wiki, as-needed, SpecRoadmap)
- Determine Standards vs non-Standard, if non-standard OASIS doc or wiki (required, SpecRoadmap)
- Define Use Cases and & Requirements (perhaps even before previous steps) (wiki or doc, as-needed, DelegatedUIUseCases) . Even though this is optional, this is a very valuable tool for helping to get general understanding and prioritization across the TC members. It is also a helpful resource for those who have no background with previous TC discussions or pre-TC submissions, it will help with on-boarding new members or non-TC members better understand the motivation.
- Primer (wiki or doc, as-needed) . Helpful to explain the specification in a non-specification way, more natural to the intended audience.
- Test cases, suite and other considerations (wiki or doc, as-needed) . Materials helpful to define set of tests for validating specification.
- Standards-track documents . Most of the time these are what we call 'specifications'.
- Non-Standards-track documents . Documents that are worthy of possibly public review and broader publication through OASIS.
- Wiki pages . Typically used for live documents or ones that have a more informal status than full OASIS publications. These will have limited review and no official status when producing standards-track work.
Organization of the UCR document follows the https://dvcs.w3.org/hg/ldpwg/raw-file/default/ldp-ucr.html#organization-of-this-document, may have only a subset of the sections. UCRs may be Wiki pages, though TCs may decide to publish more broadly as OASIS non-standards notes which get more publish review. TC members should weigh delivering needed content in support of a specification over elegance and purity of UCR constructs, ie there is no use case police.
It is often helpful to tag items to indicate either what are the proposed items for various releases or ones that require more discussion or work (TODO). Updating the status of this document will help.
Example of tags: 3.0 - proposed 3.0 content; backlog - proposed backlog content; TODO - outstanding action or question
The preferred (and continuing devlopment of) https://github.com/darobin/respec which was originally developed for authoring specifications for W3C, has been updated for OASIS at https://github.com/sspeiche/respec.
Note that the specStatus valid values match that of the http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#stage
The http://www.w3.org/respec/guide.html is still mostly valid for OASIS usage with the exception of the document status.
Best idea is to either use the existing http://sspeiche.github.io/respec/examples/oslc/template-spec.html from https://github.com/sspeiche/respec/tree/feature/oasis-style/examples/oslc. An example of it being used within Core can be found http://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/specs/resource-preview.html as well.
ReSpec has the ability to generate an HTML snapshot that could be used for developing OASIS documents for distribution (committee specifications, public review drafts, standards, etc.). The URLs in the document under version control are different than the URLs that would be to the published OASIS documents. Currently these changes have to be done by hand on the generated ReSpec HTML snapshots. There are also other changes that have to be made including specific OASIS footers that have to be included in the corresponding PDF documents. ReSpec HTML generation could be updated to automate these changes, reducing the repeated effort necessary to publish TC work products to the OASIS document site for public access. This manual process has been done to product the OSLC Core committee specification draft and committee specification public review draft. PublishingOSLCCoreSpecs may be useful in informing changes to ReSpec to automate the steps.
Technical specifications are typically targeted towards readers who are implementers of specification. So they care very much about what they need to do in order to be compliant. So care should be taken to make sure this is as obvious as possible. Additionally, readers will want to know how they can use the specification to build an interoperable solution. Care must be taken to address various interoperability scenarios.
The Primer or other supporting documents are good for helping all audiences get a good understanding of the technology and how it can be used. The introduction section, and various other sections, in the specifications should still strive to provide just-enough primer-like and non-normative (or normative) content for ease of comprehension.
In progress
Discussion occurring in https://wiki.oasis-open.org/oslc-core/VocabStableURINotes regarding alternatives and approach.