Documentation (Knowledge Management)

  • Publication of OGC standards documentation is outdated, the documents are difficult to navigate and read, and there are not enough examples. The OGC desperately needs to begin pubishing OGC standards as HTML. Further, programmers want examples. The actual standards document should be a reference and not required reading.
  • How can we make it easier to position documentation (standards) for implementers/developers?
  • OGC standards all need some level of primer that provides use cases and examples of how each standard is used and which interoperability problems each standard is most suited for solving.
    • The OGC needs to decide whether describing standards in concise and plain language is a priority.
  • Perhaps the OGC needs a new document type to accommodate processing of externally developed specifications that a community wishes to submit to the OGC. The process for this document type would be lighter (fewer OGC procedure steps required).
  • Naming of OGC standards need more consideration. The name of the standard should provide a strong hint as to the interoperability problem being addressed by the standard.
  • 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.
-- TrevorTaylor - 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
 
Edit | Attach | Print version | History: r8 < r7 < r6 < r5 | Backlinks | View wiki text | Edit WikiText | More topic actions...
Topic revision: r7 - 26 Jul 2013, AdrianCuster
 

This site is powered by FoswikiThe information you supply is used for OGC purposes only. We will never pass your contact details to any third party without your prior consent.
If you enter content here you are agreeing to the OGC privacy policy.

Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding OGC Public Wiki? Send feedback