Remote sensing exercises: protocol conventions

Latest revision as of 16:29, 11 December 2013

These are the conventions for the protocols which are to be written in the course of the Remote sensing image processing with open source software lecture. The protocols will serve as blueprints for the QGIS exercises articles.

[edit] Use present tense!

Keep in mind that you want to explain to other people (i.e. wiki-readers) how they can reproduce what you did in the exercise. The result should read very much like a technical manual, so present tense is the appropriate form.

[edit] Provide screenshots

For others to better understand your work, it's good to use images of what happens on screen, so please provide a few screenshots. You don't need to take a shot from every selected menu or confirmed dialogue! As a rule of thumb, 2--5 screenshots per exercise should do. A good means for others to keep track of the tutorial are screenshots of the results of an exercise -- So they can see what their results should look like, if they've done everything right. Screenshots should be taken with a resolution of 1000x1000 pixels.

If you don't know how to take a screenshot, see the external links section.

Attention!:

Don't paste screenshots into a word document (this includes your protocol). Provide screenshots as *.png or *.jpg. The screenshots should only contain the relevant windows (most of the time this would be the QGIS window). The tutorials in the external links section include information on how to take active-window screenshots. Refrain from editing the screenshots any further, like highlighting certain buttons or menus in MS Paint. We will add such features ourselves, if necessary.

[edit] Highlight specific elements of the workflow

To make wiki-articles more readable and understandable, we want to highlight certain elements of the workflow. Please use the following conventions:

Paths

Highlight paths to files used for the exercise are stored, in the following way: ''X:\Path\to\some\file.txt''

Keys

you press or click: These can be buttons you press on the keyboard (e.g. Enter), or buttons on the screen which you click (like OK in some menus). Use double brackets to highlight them: ((Enter))

Text you type

Sometimes during the exercise, you need to type some text into a textfield. This will mostly be commands you type into a console. Use greater/less signs to highlight them: <<some.command -some -option>> Note that this doesn't count for paths you select to store files! (See above).

Menu items

A frequent element of everyday computer work consists of clicking your way through menus to find a specific function. E.g. to save a file, you need to select File and then Save as.... Use arrows or minus-signs to separate the selected menu items, and enclose the whole chain of items in curly braces like this: {{File --> new --> Text document}}

[edit] External links

• take-a-screenshot.org -- A straightforward tutorial on how to take screenshots on Windows and Mac OSX.