Welcome to the ERGuidance web

Purpose

This documentation is presented to provide Innovation Program Authors and Editors with the resources and guidance needed to develop quality Engineering Reports and related documentation for public release through the OGC process.

Objectives

To ensure that ERs are consistent in content and style and informative to members who were not Testbed participants.

Guidance

General items for an intitial review.
  1. Identify all empty sections. If the section is not needed (it was a placeholder, never completed), then delete. If the content is required, but missing, contact the editors.
  2. Spelling. Use an editor that highlights spelling errors (such as ATOM). Fix them all. Sorry folks, but we write in American English so mind your Ss and Zs.
  3. Acronyms. All acronyms must be defined the first time they are used. No exceptions. Ever.
  4. Domain specific "buzzwords." Like acronyms, some users will not understand some domain-specific language (particularly true for the Aviation and Defense domains). Please explain all non-obvious content.
  5. Voice. All reports should be written in 3rd person. Nothing should say "we."
  6. Grammar. No incomplete sentences (like this one). Use direct language, not a super big bunch of adjectives (like in this sentence).
  7. Lists. When using bullet lists, only use a colon (:) at the end of the sentence leading into the bullets if each bullet is a short concept and not a complete sentence. Bullets that are stand-alone sentences are introduced by a stand-alone sentence.
  8. The problem with "it." "The map relies upon a single Web Map Service. It is part of the NSDI." Does "it" refer to the map or the WMS? Be clear in referencing previous sentences.

FAQ

  1. Q: Any way to automatically insert correctly numbered Figure captions?
Figures can use the following mechanism to add proper numbers and to allow referencing in text such as "...as illustrated in Figure 3."
[#id_of_image,reftext='{figure-caption} {counter:figure-num}']
.Image caption goes here
image::images/overview.png[width=600]
Key here is that this mechanism is required by all figures in a document, otherwise the counter does not work properly.


Topic revision: r6 - 01 May 2017, GregBuehler
 

This site is powered by FoswikiCopyright © 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