Topic: Specification Document Format

The current documentation production system, in which documents are edited in Microsoft Word and then published in Portable Document Format (PDF), has been criticised for the focus on one editing tool not a format and for the use of a paper format in this digital age.

Aspects to consider:

• Styling of constructs (requirements, ...) should be included in the template, and preferably enforced
• Numbering and cross-referencing should be automatic
• WYSIWYG editing preferred by some, while text based is preferred by others
• We may want to publish from a single source to multiple output formats

Possible candidates for the source format

• Microsoft Word (used now)
• DocBook (XML based)
• Markdown (wiki-like format, tested in GeoPackage SWG together with GITHUB)
• reStructuredText (RST, also included in GeoPackage SWG test)
• ...

Possible output formats

• PDF (essential, main distribution format used now, easy to add comments on draft specs)
• HTML (essential, on-line publishing, well indexed by search engines, ...)
• ...

It could also be considered to generate different types of documents from a single source. The official standards text, an overview of all requirements in the text, the one-page overview only, ...

Relations to other topics

Related to TopicExternalResources, since the creation of documents on GITHUB would only make sense if the format were in HTML, or Markdown, or some other format using line oriented storage (a requirement for the current generation of Distributed Version Control Systems like Mercurial and Git.

Related to TopicSpecDocPolicies, since the Mod.Spec puts specific requirements on documents that may be helped with a good template & format.

OGC should explore the use of Digital Object Identifiers (DOI) for standards documents, schemas, academic papers about standards, datasets and web services along with considering becoming a DOI naming authority.

Discussion

Indeed, MS Word is a nightmare. Unfortunately, with a tool as bad as MS Word and the manifold tweaks people (including myself) have found it is hard to auto-translate into HTML. Some people may think of reStructuresText (reST, not REST) - a tentatively "primitive" format which may make specs more uniform and can be translated into other formats. BTW, IETF publishes its RFCs in flat ASCII...

-- PeterBaumann - 30 Jun 2013

---

One challenge with these documents is that, whilst they undergo considerable peer review, they are not indexed by citation databases and their authorship is not recognised. Having them indexed would provide a number of positives including encouraging academics to contribute as well as providing a mechanism for OGC to measure use.

-- DavidLemon - 03 Jul 2013

---

I agree that documents should be on the web, with links to headings, even paragraphs. Should look at the ways this is done by IETF and W3C, maybe pick the best characteristics of each.

-- PeterRushforth - 11 Jul 2013

---

While having OGC standards and specifications available as html would be good, I also like PDFs quite a lot because it allows me to easily add notes and comments. This really helps a technician that actually works with the standard itself.

However, what I've repeatedly requested but which just does not seem to be made publication policy: OGC should auto-generate bookmarks and document internal links for each specification that is published as PDF! This is so easy with the tools we have (e.g. Microsoft Word) and is such an improvement for all users working with the specification (quickly jump to a section). It is very inefficient to have each user generate bookmarks for chapters and sections on his own. So why not make auto-generated bookmarks for PDFs an OGC publication policy?

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

-- Frank Suykens - 4 Jul 2013

From GeoPackage SWG:

Staff has been studying GOC document migration for years, and DocBook has been a leading candidate. I actually agree with you [Pepijn Van Eeckhoudt] that it's a great format for specification document work. However, I haven't found much support within the membership for using it -- too little familiarity with it, and too few WYSIWYG editors. While RST and Markdown offer less functionality, they seem to be more accessible to the community of interest. The full story is too detailed for an email, but I'm happy to offer more background offline (or in a future ideas4OGC meeting), but in short, if you can build some support within OGC for DocBook (especially with key spec editors -- Herring, Cox, Vretanos, Nebert, Daisey and Botts come to mind), then we can consider a DocBook experiment similar to this one.

-- Raj Singh - 5 Aug 2013

---