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.

see OldOgcPoliciesAndProcedures#SpecModel

Relations to other topics

Related to Topic..., since ...

Discussion

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...

-- PeterBaumann - 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.

-- SimonCox - 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 LaTeX 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.

-- AdrianCuster - 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.

-- AdrianCuster - 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.

-- TrevorTaylor - 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

-- TrevorTaylor - 15 Aug 2013