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.
9. Tense. The engineering reports are published after the end of a testbed or other IP initiative. Therefore, the engineering reports should be writted in the past tense.

Recommended Asciidoc Environment

We recommend to use http://asciidoctor.org[asciidoctor] and http://asciidoctor.org/docs/convert-asciidoc-to-pdf/[asciidoctor-pdf] in combination with the https://atom.io[Atom] editor.

In Atom, you should install the following packages (under Atom/Preferences/Packages):

* asciidoc-preview
* autocomplete-asciidoc
* language-asciidoc
* markdown-writer: requires changing of key-map to allow for keyboard shortcuts such as e.g. bold*
platformio-IDE-terminal

This environment allows you to use keyboard shortcuts, autocomplete, syntax highlighting and a rendered preview for asciidoc; and provides you an terminal window within the editor to convert your asciidoc to html and pdf.

Installation on MacOS and Linux

* Please follow the steps on https://asciidoctor.org/#installation.
* Install the bibtex extension: gem install asciidoctor-bibtex

Installation on Windows

We have made best experiences with the following steps:

1. Install ruby for windows: https://rubyinstaller.org/downloads/. If you experience any issues, the following link may help: https://stackoverflow.com/questions/18908708/installing-ruby-gem-in-windows[stackoverflow]
2. Open command prompt and install two gems:
   1. Execute: "gem install asciidoctor"
   2. Execute: "gem install asciidoctor-bibtex"
3. Text your installation
   1. Open a folder that contains your Engineering Report asciidoc source files, including the er.adoc file.
   2. Execute the following command: _asciidoctor -r asciidoctor-bibtex er.adoc_

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.

1. Q: My table does look right in PDF, what can I do?

Simplify your tables as much as possible. Remember that the tables fit in portrait layout of A4 paper with normal margins, so the fewer the columns the better (3 or 4 columns with minimal text work fine). By default, the columns may not auto fit, so please specify column width by percentages, such as: [cols="25e,25,50"] NOTE: percentages must equal exactly 100%.

---