By Scott Simmons / Executive Director / Standards Programs Open Geospatial Consortium / www.opengeospatial.org
The problem with standards is that a standards document is difficult to read and convert into a product. A standards document must be clear, internally-consistent, and testable… but there is no requirement that it be friendly. The Open Geospatial Consortium (OGC) has evolved the format by which its standards are published to facilitate coordination with other standards bodies and to ensure that implementations against those standards are compliant. We acknowledge that this format is not particularly friendly to software engineers and developers. See Figure 1.
FIGURE 1.
The problem is that a standards document is a complicated document.
We publish standards to meet market needs and the only real measure of success of these standards is how frequently or broadly they are adopted. Recognizing the importance of adoption, we have initiated an effort to develop “implementer-friendly” standard docu- mentation. This work is driven not just by the need to increase adoption, but also by feedback from our user community and members, including through our Ideas4OGC process [http://external.opengeospatial. org/twiki_public/Ideas4OGC/WebHome].
Rapid prototyping of OGC Web Services software should not require that a developer understand the nuances of geodetic concepts; rather the developer should simply code against requirements. The development management and quality assurance process can include the requisite experience to ensure that the software is correctly addressing the geospatial concepts.
WHAT WILL THIS NEW DOCUMENTATION LOOK LIKE?
In short, an implementer-friendly standard will:
be an alternative view of a standard; be light in text; reference background information from the normative (official) standard, yet not include that information; include sample code; provide links to sample data; highlight reference implementations in the open source community; and be published in an easy-to-use format such as HTMLand/orinGitHub.All OGC standards must adhere to a number of quite strict requirements to ensure that these stan- dards can be implemented. Each includes a number of specified requirements and an Abstract Test Suite in an annex. The implementer-friendly view will make these requirements the most prominent part of the document. The requirements will be presented in an order and grouped according to the sequence in which they should be implemented. Each requirement will be accompanied by sample code, pseudo code, and/or implementation advice. Our goal as a standards body is to ensure that the tremendous work contributed by our Standards Program membership is distilled to more of a how-to guide than a detailed reference manual. See Figure 2.
FIGURE 2.
This is an example of how an implementer-friendly view might be formatted.
Critical to this alternative view is keeping text to the minimum required to describe the methods necessary to implement the standard. Of course, some context is needed, but deep technical background or discussion of use cases is not critical as primary content for a developer. Such information is best provided through a reference back to the normative text.
Sample code and data will ideally be created or identified as part of the standard development process. For example, both the OGC GeoPackage Standard and the SensorThings candidate standard were developed simultaneously with participants creating test implementations of functionality as it was defined in the draft standard. Some Standards Working Group participants can choose to release pieces of their code as samples. OGC staff will assist in curation of such samples, but we do not plan to validate that each piece of code is correct – we assume that the community will self-vet the content.
The implementer-friendly view needs to be published in a format familiar to and useful for developers. HTML is an obvious candidate and certainly the simplest to manage, but we are also considering GitHub or other collaboration environments as mechanisms to host the documentation in a publicly-accessible repository. Regardless of the publishing environment(s), it is incumbent upon OGC to ensure that the content is synchronized across each.
HOW WILL OGC MAKE THIS HAPPEN?
The concept and goal of the implementer-friendly standard effort has been discussed in various OGC member forums and subjected to strategic review by our Board of Directors. We have broad support and commitment by the people who actually do the work to create standards.
Initially, prototype implementer-friendly views will be published to a publicly-accessible OGC wiki page [http://external.opengeospatial.org/twiki_public/ Main/StandardTemplates]. OGC staff and invited experts are working on the prototypes using guidance received to date from our membership and Board.
We will request that our members and the public comment on the views. To be clear: the OGC always relies upon public comment and requires that the input from the public be considered before any OGC document is allowed to be approved in our process. Once the OGC members and public weigh in on the proposed content, adjustments will likely be made to the prototypes and formal guidance will be created to explain how the implementer-friendly standards will be published. The OGC membership will vote on this guidance document.
We envision the implementer – friendly standards to be living documents with OGC member and public contribution of sample code, data, and implementation advice. The initial publication of each will likely be somewhat thin on this extra information, but we will encourage the growth of informal documentation that supplements the official content.
Mechanically, all of the requirements and background information in the implementer-friendly view will be pulled directly from the published normative OGC standard. Each OGC standard is created, approved, and published to a specific normative version. Our end users expect that such normative versions are strictly controlled. Fortunately, OGC standards are now published in HTML and the implementer-friendly (and potential other) views of those standards will be directly linked from the original HTML content to ensure that the view does not deviate from the normative content.
HOW CAN YOU HELP?
As mentioned above, the OGC welcomes public comment and participation in our activities. If you are implementing OGC standards, take a look at our new view for select standards and let us know if those views make implementation easier. Suggest improvements to the view. Submit sample code, sample data, or advice (even if informal) that can be included as extra information in the implementer- friendly version of a standard.
