OpenCPN

Plugin Documentation

OpenCPN Plug-in (pi) documentation

Some rough first ideas on the set-up for OpenCPN-plugin documentation (English version)

1. The documentation has to be logical and consistent.

I have tried to put myself in the mind-set of someone who knows nothing about OpenCPN-plugins (that was quite easy actually). And then I started asking myself some questions. The first question about the pi was: "What is it", the second "Why should I want it", the third "How do I install it" and so forth.

My conclusion was that I probably would appreciate a standard framework (for each pi the same framework). Maybe something like this:

  1. What and Why

  2. Install

  3. Standard actions

  4. Options

  5. FAQ

Explanation:

  1. What and Why

    1. What does the pi do

    2. Why can the pi be useful

  2. Install

    1. Where to get the pi

    2. How to install the pi

  3. Standard actions

What are basic (standard) actions you have to do to make the pi work Example: “how to set up a Watchdog Alarm”.

  1. Options

What options are there after performing the standard actions

Examples: 1. Choice for a specific type of Watchdog Alarm (anchor, boundary, speed, course, deadman, NMEA etc.) 2. Choice for a specific type of alarm-signal (pop-up message, sound, command) 3. Setting various parameters (range in meters, degrees, time in seconds or minutes, speed etc.)

  1. FAQ

This section is meant to deal with various questions that might arise when using the pi. Example:

(Why) Can(‘t) I …….. ? Answer: ……..

2. The documentation has to be easy to understand.

*The problem: The English language is spoken in many different parts of the world. And in different ways. I’m Dutch and (I think) I can write a bit of text in English. But what I presume to be a more or less correct usage of that language might be quite upsetting to a native English speaker. So: text can lead to miscommunication/misinterpretation. And to complicate things: OpenCPN’s default English is "US" English and therefore (I realize I’m not making friends in the USA now….) not quite "the real thing" either.

The proposed solution: *Visualise. That means: less text (not so easy for me) and more screenshots. Less text also means: don’t try to write "a lot of words" for things that are already obvious and don’t need further explanation.

*Example: We can write a whole story (equals "lots of words"…) about how to set up an anchor alarm, but another way to skin the cat is to visualize it by means of a series of screenshots. Like this:

Setting up an Anchor Alarm in Watchdog-plugin:

Step 1

s-wdpi-50.png

Step 2 s-wdpi-51.png

Step 3 s-wdpi-52.png

Step 4 Click Anchor and OK image

Step 5 Edit the alarm. Fill in and click OK. For explanation of the different items: see text a to h

s-wdpi-50.png

  1. Click Sync to Boat or enter Latitude and Longitude. ​ Sync(ronize) to Boat = alarm is set for the position of the boat at the moment the alarm is enabled.*

  2. Adjust Radius if 50 is too much or not enough. Radius = the distance in meters before the alarm is triggered.

  3. Automatically synchronize to the boat whenever enabled Tick the tickbox if you want the alarm to be set for every new position of the boat at the moment the alarm is enabled again. Leave unticked is you want the alarm to remain relative to the position in step a.

  4. Sound, Command, Message Box Choose one or more types of alarms.

  5. Browse Choose sound-file to be played (only when "Sound" is ticked).

  6. Repeat Alarm after .. seconds Adjust if 60 is too much or not enough.

  7. Automatically reset Re-sets the Alarm automatically after you have responded to a alarm.

  8. Graphics enabled Draws a circle around the boat, showing the radius.

  9. Test To test the alarm

  10. Information, OK and Cancel No further explanation necessary