Topic: Specification Document Policies
The policies and requirements for the creation of new specification documents are complex. This causes confusion.
There are currently a large number of different sources of injunctions for standards documents but it is not clear exactly where the formal list of injunctions can be found.
Current TC rules require that all new specifcations comply with the rules of The Specification Model --- A Standard for Modular specifications
OGC 08-131r3, commonly called the "Mod.Spec.". This rule has been criticized as inhibiting the ability to write new standards, as leading to more complex (or longer standards), and as being hard to understand. Conversely, this rule was adopted to, and has been praised for, making clearer standards that lead to better implementations. The requirements of the 'Mod. Spec.' have radically increased the amount of work for specification writing for instance, adding all the conceptual work which used to be part of the paid work developing test suites to the specifcation writing process. The increased burden slows the development of new specifications, while the lack of financial shift reduces the incentive for specification writers.
The 'Mod Spec' also has a number of issues. Since all new specification documents are required to conform to the requirements of the 'Mod Spec' those issues are blockers for progress. However, no one, not even the OAB which originally wrote the Mod Spec, is held responsible for keeping the specification writing process functional. A full rewrite of the 'ModSpec' is currently pending as a comment against the document.
Both the Template and the Guide for new specifications were created partially to address this complexity. However, maintenance of the template and guide has not been identified as a primary priority of OGC Staff so that errata and proposed changes take a long time to land into a new document. If standards are at the core of the OGC vision, the tools for writing standards should have high priority for OGC activies and OGC Staff.
The requirement to label specification documents, specification clauses, requirements, requirements classes, conformance classes, and conformance tests with formal identifiers, issued as HTTP URI by the OGC Naming Authority appears to be accepted, common practice but is apparently not a formal requirement.
Relations to other topics
Related to Topic..., since ...
Let me open my mouth, as we (WCS.SWG) were the first ones (and maybe still the only ones) doing a full suite of 17 specs along the mod spec model. It was a hell of a lot of work, but mainly due to the fact that we were the enrepreneurs. Meantime we have a slate of best practices which work out quite well, and these specs are generally appreciated by users (=implementers) as being much more comprehensible and transparent than the previous monolithic version. So I'm all for it.
However, a major issue is that the mod spec model has some conceptual shortcomings - not so much because it would be flawed (I do like the approach in general), but because some core issues just have not been addressed in the mod spec itself. Needs to be corrected, urgently.
Which raises the same issue as with OWS Common: How can OGC let float something that is at the heart of its mission? Bot mod spec and OWS Common WGs have been dissolved following delivery of something that does not have been tested thoroughly; has no reference implementation; has nobody to take care of in a managed process. Breathtaking...
- 30 Jun 2013
Remember what problems the Modular Specification was crafted to fix:
- making specifications testable
- managing dependencies (at the appropriate level of granularity) while also taking care of 'versions'
- allowing implementation of parts of standard
- providing clear extensibility mechanisms
These issues interact strongly with each other.
The OGC modular specification policy appeared to provide a mechanism to deal with all these issues in a rather elegant way. While it has clearly been hard to swallow for some communities and editors, if the policy is changed, then it is important that all these concerns are still addressed.
- 25 Jul 2013
Help in templates and editing to obtain well readable, consistent standards texts
We notice that a lot of time is spent on formatting and editing of the standards' text. This time is spent by members that are typically the technical experts rather than technical writers or Microsoft word guru's.
Some ideas around this:
- Use DocBook
or similar to allow SWGs to focus on content rather than form. This would allow easier web publishing.
- Provide a good template for this. Make sure that all elements (e.g. requirements, term definitions, XML snippets) have a defined style in the template.
- Rewrite an existing standard using the template to show the best practices. Spend enough time to get this right and all new standards will benefit by the example. Some of my people gave IETF RFCs as a good example
of consistent specifications that are quite well readable.
- Change or drop the ModSpec
requirements. It takes time from the writers, while the readability of the standard does not seem to improve proportionally.
- OGC should provide professional editing services to improve the texts
- Every standard should have a smashing one pager that provides the essence of the standard. Also here, I'd expect very active participation from OGC staff. This effort can start off the SWG charter.
-- Frank Suykens
With the publication of "The Specification Model" (aka Mod.Spec.) and
the subsequent adoption of that standard as a formal rule of the TC
Policies and Proceedures, it appeared that the TC had started a formal
process to try to write clearer standards. (Note, that this is a
separate issue from other suggestions to write shorter standards or to
write standards using different means.) Unfortunately, the committment
of the TC OAB to this work seems unclear: repairing "The Specification
Model" seems to be on a back burner.
=> ACTION: The tools for specification writing should be given a high
priority in the work of the OGC. The templates should be
kept up to date, and 'The Spec. Model' should be fixed to
ensure that at any moment a member can start a new document
with the current state of the art.
=> ACTION: The standard 'The Spec. Model' should urgently be fixed or
the requirement of the P & P to follow the document should
be changed into a recommendation.
- 26 Jul 2013
Similarly, the standards as a whole would benefit from the work of a
technical editor. Many documents have a confusing structure where
parallel issues are organized and addressed in totally non-parallel
fashion. Many documents have poorly written injuctions which are hard to
find, hard to establish against who the injuction is being made, and
which each use different word structure. The WMTS specification
underwent and the current MetOcean
Best Practices is undergoing such a
review to the apparent pleasure of the authors.
=> ACTION: The OGCi should consider obtaining the services of a
technical editor either by contracting out reviews of
standards or by bringing such an editor on staff. The TC P&P
should be modified to make such a review part of the process.
- 26 Jul 2013
On behalf of Doug Nebert:
By not managing dependencies and declaring appropriate usage, we risk having OGC standards be more like independent books-on-the-shelf than an encylopedia or integrated library. Rooting everything in the Abstract topics was a good rubric in the beginning, but it seems we have wandered away from that discipline. I would support beefing up a comprehensive general/abstract model - to include basic requirements - and then have our standards be realizations of parts of the general model. This would facilitate transformation between different implementation environments; one key benefit of interoperability is lossless transformation of content.
- 13 Aug 2013
On behalf of Paula McLeod
There is a need for a simplistic demonstration of the contribution of specs. Sometimes OGC and their members take that for granted but people are questioning the contribution of some specific specs
- 15 Aug 2013