BASIC USER MANUAL STRUCTURE

[rgleason]

The purpose of this Discussion is to resolve the Structure or outline of the entire manual.
We currently have

Main Menu	Quick Start Menu	User Interface Menu

New Flattened Structure, which reduces the number of levels to traverse and brings the Action/Task oriented commands up to the first level namespace, providing quicker access to important parts of the manual.

Changed action/task menu names to be "action" oriented for new user comprehension.
Main collector (or Container) menus such as TOOLBAR, CHART PANEL and MENUBAR (capitalized) are located at the head of their action oriented commands to help to identify where they are found.

Questions:

• Duplication of Plugin Manager - Fixed with two Plugin (Links) pages and revision of the Options | Plugins page.

Kevin Klop wrote:

1. Right now the manual is organized in a knowledge domain manner. “This is the toolbar”, “this is the right click menu”, etc. Often people don’t just sit down and read a manual cover to cover. Instead, they turn to the manual when they have a task to perform. “I need to lay out a new courses” “I need to connect to my GNSS source”, “I need to install/update charts” etc. THAT’S when they usually turn to a manual. Do we want to organize the manual around tasks rather than domains?
2. Another way to think about task orientation is to ask yourself, “What is the person asking themselves when they turn to the manual out of desperation?” Usually it’s question of either, “How do I ______” or else “Why isn’t ______ working right (or working at all)?”

TwoCanPlugin wrote

#3776 (comment)

It is certainly worthwhile having this discussion, but we'd better be careful about taking on too big a project of organization, when we still have a lot of editing DOWN, new up to date screenshots, and fixing links etc, to do.

Yes, it would be great to develop the ideal Outline for the Basic User Manual and we could move in that direction or even do the whole thing if we have time and energy.

For example, the last manual we had OPTIONS moved out to the first level. Maybe I should not have changed it.

[leamas]

Do we want to organize the manual around tasks rather than domains?

I think this is the way to go. It's a pain editing stuff which sits in a strange structure without a well defined context. Better to get the overalls right from a (a new) start. Before start editing a page it should be clear what should, and not least should not, be part of that page.

That said, we might still need a reference section corresponding to the task "WTF is this?" That is, while the GUI should be self explanatory it not always is, bits and pieces needs further explanations. Should be kept short and concise, not the place for overall info on for example how to create a route.

[rgleason]

This would be an entire rewrite of the manual, I believe. Would it be shorter, smaller and more efficient?
Would it take less time? Could we just shorthand the manual so to speak, without covering each menu item as we do now?

What would the ideal outline for this manual be?

I think this might be a heck of a lot of work, but updating the rest of the present manual will be too.

We have 8 user editors lined up and ready to fix the current manual, Toolbar to be more precise, unless we have a new outline or structure to work towards, I will have to let them just start on that

So what is the second half of this Basic Manual going to be?

We really need to get that nailed down in detail or this will become a mess and simply remain just an idea, and we will move forward with what we have noe.

[leamas]

Could we just shorthand the manual so to speak, without covering each menu item as we do now?

Definitely, IMHO. Most dialogs are self explanatory, if they weren't we would have a massive amount of user questions. The basic problem facing new user is rather for example "How do I create a route and the use a route?" This is more about pointing to the relevant dialogs than explaining each and every item in (often outdated) screenshots.

A problem not facing a new user is "What should I do with Options?" These are tools when doing various tasks, but not a task as such. Just an example

But this input came from Kevin Klops if I understand it correctly. We should try to involve him in this since he has professional experience. Such is of course always valuable, but more so at this point discussing the overall structure. And of course also @TwoCanPlugIn

Yes, some dialogs are so complicated that they require some docs. But question is if such a need shouldn't be filed as an RFE...

[rgleason]

I honestly think that we are going to have to drop a lot of details to whip this into shape, and that that knowledge is going to be lost.
Also I think trying to incorporate some of those WTF things into the structure will be difficult.
Look at the issue of having double pages with the same topic (perhaps one very simple page directing to the more detailed page usually under Options).

I have written Dokuwiki to see if there is a technique of Piping or Immediately Direct linking to another namespace, to eliminate what I call "Link Pages". Haven't heard anything yet.

[rgleason]

@leamas Have sent an email to all 8 User Editors, asking them register on github and to join this discussion on github.
This is what I sent:

Dear 2024 Editors,

Kevin and others have raised this issue:

• Should the Basic User Manual be "Task oriented or Knowledge Domain oriented." You represent the Users, the ones to whom this question should be addressed.
• What kind of manual do Users really need?
• Exactly what questions do Users need to be answered? List them please. (Very important)
• What information in the existing manual is unnecessary?
• How detailed does the manual have to be?

Also please join this conversation and contribute, discuss and focus our efforts on a manual that you would be proud of using.

I hope you all will register on github.com for a free opensource account so that you can participate in this conversation.

You may be crafting an outline for the work ahead otherwise we will go back to updating Toolbar as was planned.

This is the OpenCPN Github.com Discussion area

BASIC USER MANUAL STRUCTURE #3820

You are welcome to join the discussion. The best thing to do is to register for a free opensource account at github.

https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
https://github.com/open-source

I hope we will all be able to join this discussion soon.
Thanks very much.

[rgleason]

Ok, so it is pretty clear that several people think that the next User Question or Task is

• How do I create a route?
• How do I manage multiple routes?

So all we have to do is move "Create a Route" and "Route Manager" out of Toolbar and up one namespace, and then edit it Down.
In fact, all the Toolbar items are actionable tasks, so why not just move them up out of Toolbar (everyone knows about toolbar and we don't need that in the way!)

EVERYONE KNOWS ABOUT TOOLBAR (It is just the main container for all Tasks)
SHOULD WE JUST MOVE ALL TOOLBAR MENUS UP ONE NAMESPACE?
And just have TOOLBAR (shell or placeholder)?
Thus these would all be listed in the first level of the TOC

• How to access Options/Settings? Should this be changed to "Settings"?
• How to Create a route
• How to Route Manager
• How to set OwnShip Tracking
• How to Dim the Display
• How to mark a Man Overboard.

[torrmundi]

I agree with Kevin that the average user's ask is task-oriented:

• how do I install OC?
• how do I configure OC?
• how do I use OC to display my ship's data?
• how do I use OC to make a route and export it to my chartplotter?
• etc.

There IS a need for a reference that delves into menu functions and explains the sometimes obscure settings and choices. But that is for the knowledgeable user that has already found out a method to perform a particular task. To become a knowledgeable user is the problem every newbie faces. Having only a reference guide is daunting and time-consuming. No doubt many won't climb that mountain.

So we can profitably continue to produce the Basic Manual in it's current reference form. What remains to do then is produce a task-oriented manual.

[rgleason]

John, that's a helpful list of some of the tasks users might want to do.
I believe we have the first three questions answered in Quick Start (some additional editing might be needed). Please review and advise when you have a chance.
(I am hopeful the "Connect to GNSS" section becomes drastically simplified with the major programming by Alec Leamas and Pavel.)
I also believe that we have also answered

• How to find and install charts?
• How to personalize Opencpn?

Can you add to this list and prioritize it somewhat?

• How to Create a Route ?
• How to Manage a Route ?
• How to Export to chart plotter. ?
• How to show the Boat Track ?
• How to set Man Overboard marker?
• How to dim the screen at night?
• How to connect the ship instruments?
• How to connect to wifi?
• How to control the way the charts look?
• How to control and adjust the text on the charts?
• How to adjust the User Interface and Scale Factors?

At this point I am not sure what we are doing with regard to Toolbar if we follow this course. It might be reworked more or parts might just be dropped. That is why this discussion is necessary.

However it is quite clear to me that we next need to work on "Create a Route" and "Route Manager" and get those simplified and logical, regardless of where they are located.

[rgleason]

Will moving the Action Items under TOOLBAR in this way help to address "Do we want to organize the manual around tasks rather than domains?"

The Basic User Manual would read on the first level

• Quick Start
• User Interface
• Change Options (or should it be Settings?)
• Create Route
• Manage Routes
• Enable Tracking
• Change Color Scheme
• Get Help About <--(Moved out of Quick Start to here)
• Drop MOB
• TOOLBAR <- Just a "Task" container (becomes a single level page)
• CHARTPANEL
• MENUBAR
• etc.

[rgleason]

Having received no clear response to this proposed change, I am proceeding with these changes. Everyone has simply talked around the question.

Making these changes is kind of a PITA and it will not be undone.

[KevinKlop]

Hi! Just acknowledging that I’m finally here and reading through this thread…

I think there is a slight misunderstanding. There is always a need for an item by item reference. After a person can do their basic tasks, eventually they are going to ask, “hmmm.. wonder what THIS does…” and that’s where the reference section comes into play. However, people generally want to accomplish something.

in OpenCPN”s case, what are the things that the person wants to do first?

1. Install OpenCPN
2. Get/update charts
3. Create a route
4. Connect to some gps source so that they have moving-map functionality

what else? Connect to NMEA bus, both 183 and 2000? Connect to RADAR? What about tablet users? And of course installation on windows and Linux and Mac and android are all different. Oh, and Raspberry Pi.

When you get a new appliance, the first part of the manual is a quick overview of the buttons (though that is arguably very short -2-3 pages, maybe four). The rest is task-focused.

if you get a new computer, the manual doesn’t say, “this is the a key, this is the b key”, etc. it says “how to set up your computer”, “how to connect stuff” etc.

then, often in the back, is the reference section that goes into all the whozits and whatzits and advanced stuff that a person might want to zero in on once they can use the fershlugginer thing at least a bit.

how do they get GRib files to display? How do they update their charts? Do we talk about o-charts?

editorial decision has to be made about how much documentation do we do for plug-ins… or do we simply provide space for the plug-in creator to put their own documentation?

Another question that might be asked is how to control an autopilot or how to network OpenCPN with other OpenCPN or non OpenCPN, etc.

I realize this is a daunting thought and sheer amount of new content might seem tremendous. It doesn’t ALL have to get done at once, as it’s a philosophy rather than a directive and it can happen as transition.

an alternative might be to put this in the back under a “how do I?” Section, though I would argue strongly agains that organization, it’s still better than nothing.

[KevinKlop]

And to be clear, I understand who “the boss” is. I’m not going to try hard to upset the applecart here!

[leamas]

On the contrary, twice ;)

There is no boss besides Dave, and he has not taken part in this discussion. The dogma governing the project is basically "thou shall hove no other Gods than Dave". Besides that , we are all equal.

Of course, some devs are more equal than others, but still...

I’m not going to try hard to upset the applecart here!

By all means, please do! I think we all could appreciate honest thoughts about the current docs and how to move to something better. If this means upsetting the applechart, so be it. Compromises are inevitable, but we don't need to start with them.

And you have something extremely valuable: fresh and professional eyes. Let us hear what you think before you lose these oh so valuable first impressions.

[rgleason]

I've added a link page under Quick Start for "Manage Plugins"
https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:get_started:manage_plugins#manage_plugins

This will have to suffice for the time being.

[leamas]

what else? Connect to NMEA bus, both 183 [...]

• Handling plugins. A short overview of the plugin ecosystem. For many users, one or two plugins is extremely useful. For European users the o-charts plugin is more or less mandatory to get working charts.

[leamas]

itorial decision has to be made about how much documentation do we do for plug-ins… or do we simply provide space for the plug-in creator to put their own documentation?

There is a separate plugins manual compiled from different plugin sources here

EDIT: BTW: This is made using Antora. The sources are spread out, each plugin source tree contains a manual/ directory. Antora collects this to a common piece. For plugin maintainers Antora is not that visible, the manual is basically just an Asciidoc page with some images.

[KevinKlop]

The problem with this, when task focused, is that some tasks require speaking about plugins. For example, how do you get charts without the downloaded? Ditto with GRiBs…

[leamas]

The grib plugin is bundled. But in general we indeed need an early introduction to the plugin system (max two pages). And then reference this in later places.

[leamas]

That is, there is a task "install a plugin" which is required by other tasks.

Documenting is not that differerent from coding.

[KevinKlop]

While the grib plugin is, indeed, bundled, it’s still a plug-in. Do we give favouritism to some plugins and not to others? If so, which ones?

what about weather routing?

what about o-charts, which is a commercial entity but is pretty much required outside of some localities, (I love o-charts, being in Canada), etc. it is a policy decision that will need to be made.

[leamas]

The bundled plugins are, technically, not plugins. They are part of the same source tree as main OpenCPN. "Favoring" these is just about favoring some part of the source code, hence a non-issue.

Furthermore, we have a tight relationship with the o-charts community. I seriously doubt that anyone here has a problem with that this is a commercial entity. That we endorse them is a policy decision I would say already is made. They certainly endorse us , so to speak.

Overall, while the project is indeed open source mainly under GPL-2+ the community is far from kosher. We have a more practical approach. One example is this user manual which is not distributable in Linux distros, it cannot be rebuilt form sources.

[leamas]

@KevinKlop: Welcome aboard!

[KevinKlop]

Thank you

[torrmundi]

Find and install charts isn't over yet!

• O-charts has the most miserable shopping experience. You do not get any sense of what the chart quality may be, nor can you find a list of countries included in the packages. You have to compare their gross resolution maps with a good chart to figure out if an island may be included in the package. But at what resolution? What data is in the charts? Who knows without spending the $ or Euros?

• MBTiles are a valid charts source, but it's ignored by the manual, except for NOAA. Here's a list of sources. But I'm not sure if we want to include such a random list of user pages from the web, however useful. They seem persistent, but could disappear at any moment. Do we have automatic link checking in the Dokuwiki?

This was all prompted, in my case, by a lack of charts for Bahamas and Turks and Caicos.
After a quick skim of the chart installation section of the manual, I don't see anything about installing MBTiles.

Links to MBTile Chart Sets

[Soggy Paws' Charts](https://svsoggypaws.com/SatCharts/index.htm)
"Soggy Paws"
Red Sea, Mediterranean, Malaysia/Thailand, Philippines, Indonesia, Micronesia, Marshall Islands, Papua New Guinea, Solomon Islands, Fiji Between Fiji & Marshalls, Tonga, Cook Islands, French Polynesia, San Blas Islands, Panama

[Migration's Charts](http://chartlocker.brucebalan.com/)
"The Chart Locker"
Pacific Mexico, French Poly, Pitcairn Island, Easter Island, Central S Pacific, Western South Pacific, New Zealand, Japan, Taiwan, Western North Pacific, Bahamas, Turks & Caicos, parts of East Caribbean, etc. mbtiles 2020-2024

[Valhalla's Charts](http://svsoggypaws.com/terrystopics.htm)
(Terry's Topics)
SE Asia, Indian Ocean, and Western Pacific . Also, CM93 v2 Download for OpenCPN.  Downloadable anchorage waypoints in GPX format. mbtiles

[Ocelot's mbtiles Charts](http://svocelot.com/Cruise_Info/Equipment/Chart_Downloads.htm)
SE Asia, Western Pacific, and Indian Ocean
As of Jan 2024 added French Polynesia, the Cook Islands, Samoa, Tonga, Fiji, Vanuatu, & New Caledonia. I've also added the Canaries & Cape Verde islands off the NW coast of Africa

[Zen Again's Charts](http://yachtzenagain.blogspot.com/2015/04/googleearth-kap-library-for-opencpn-and.html)
Pacific Ocean, SE Asia, Crossing to S Africa, S Atlantic, Brazil (older)

[Jacaranda's Charts](https://www.jacarandajourney.com/geimagesoffp)
French Polynesia

[Amazing Grace's Charts](https://sailingamazinggrace.com/charts)
West Coast USA and Canada, California to Alaska. New in 2023.

[Soggy Paws' Charts](https://svsoggypaws.com/SatCharts/index.htm#mycharts)
Red Sea (Complete), Philippines (Partial), Papua New Guinea, Solomon Islands, Micronesia, Marshall Islands, Fiji, French Polynesia

I'll look at Quick Start for

• how do I install OC?
• how do I configure OC?
• how do I use OC to display my ship's data?

My prioritized list

• How to connect the ship instruments? (NMEA via WiFi, USB)
• • How to filter redundent/unwanted NMEA - OpenCPN cannot filter by device ID; only by sentence types (e.g. to block $YDMTW)
• -- The Yacht Devices WiFi gateway may be used to filter by device IDs and/or message types.
• How to connect to wifi? (and how to get both your Starlink WiFi and your Chartplotter WiFi working simultaneously for a device)
• How to select from various charts and the use of Chart Groups
• How to control the way the charts look?
• How to control and adjust the text on the charts?
• How to Create a Route ?
• How to Manage a Route ?
• How to Export to chart plotter ? (as well as re-importing from my chartplotter after running the route and making changes there)
• How to show the Boat Track ?
• How to dim the screen at night ?
• How to adjust the User Interface and Scale Factors?
• How to set Man Overboard marker? (I'd only use my chartplotter for this purpose)

My biggest needs on a day-to-day basis are:

• getting weather (Predictwind, Windy, Luckgrib, Marv's Weather, Aquamap)
• Integrating weather with routes, either on a designated startpoint>target or what-if (where could I go in this wind?)
• Evaluating water depths, tides, currents
• Know traffic around me (radar, AIS)
• Knowing about anchorages & dockage, including reviews (ActiveCaptain data, Waterway Guide data, NoForeignLand)

[torrmundi]

sure.

[torrmundi]

Done, please take a look. Re-organized, added internal and external links, corrected spelling and caps, added some details (particularly in explanation of MBTiles/KAPS).
Is it too much? Too wordy? Trying to strike a balance, I've cut a bit already.

[rgleason]

Please provide a link to the page. Thanks Rick

[torrmundi]

Sorry, my bad! See:
https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_advanced:charts:mbtiles, and
https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_basic:get_started:chart_install:other

[rgleason]

John, I like what you've done in the Advanced Manual!

Can you review the the page in the Basic Manual about Chart Alternatives
to see if it aligns ok?

Also please consider that the Basic User Manual is hopefully going to be distributed for offline use as a PDF and the Advanced Manual will eventually become a PDF download. We have to do this because of size.

Thanks. Rick

[Spiv13]

Hi all,
Sorry for the late entry in the discussion, I am getting ready to fly from Oz to Greece and get my boat ready for a crossing of the Red Sea and the Indian Ocean in a few months, so my input will be less than I would have liked.

I have been using O for more than 15y, also during a circumnavigation.
Unfortunately I cannot use all the more advanced features as I never had the time to actually study the manuals, I tend to look for a concise instruction such as: Tools>options >Display >Advanced.
Rather than a description of why and how it works.

So my suggestion is to make each element of the manual as short and simple as the above instructions and then provide a link to "more info" if required.

[leamas]

Thanks for valuable input. Seems that many of us are heading in a similar structure direction:

1. Installation and initial setup, which is starting to take shape
2. Usage: New section on things how to work wit h routes, tracks, screen, plugins, ...
3. Reference: Detailed description of dialogs, focusing on more convoluted items which needs to be explained. Much of this sort of exists, bit needs tons of clean up. Usage descriptions in 2) links to these in many cases.

[Spiv13]

I would like a section dedicated to Layers.
They can be Very useful once mastered.

[rgleason]

Yes please. We need to find a better home for layers.

[rgleason]

@Spiv13 I think there should be a brief Layers page (under Routes?) with a link to Advanced User Manual where the use of layers can be more detailed.

Under Routes > Layers we have several pages. These should be edited and I've made a Layers page under the Advanced User Manual

[rgleason]

Since nobody responded to my question above, I went ahead and did it.
See revised first Post

New Flattened Structure, which reduces the number of levels to traverse and brings the Action/Task oriented commands up to the first level namespace, providing quicker access to important parts of the manual.

Changed action/task menu names to be "action" oriented for new user comprehension.

Leamas suggestion for a "Reference" section, I believe is actually

• "Change Options"
• "Advanced Manual"

where a lot of that detail should be located.

[leamas]

You still miss it. This is not task oriented, it reflects the UI. Some examples:

• The second "task" is "Change Options". I really doubt a new user has a need to do this, their needs are things like handle routes, personalize the screen, etc.
• A task like "Manage the screen" will actually stretch into several GUI components on different levels: night modes, layers, fonts.

But the most important thing is that a task oriented description should be kept short, more like an overview. But you then need another place for the complete UI nitty-gritty details. If you don't separate this it will IMHO not be possible to create readable, task oriented description.

But in the end, if this is the way you want to do it.... But I should really try to get feedback from others before going along the path you describe.

If the fact that you have done changes is a reason it's not possible to do another way it's quite a verdict over the current environment.

[leamas]

@KevinKlop @Spiv13 @TwoCanPlugIn ^ Thoughts?

[rgleason]

Alec, we have a lot to accomplish in a short period of time. The structure for this 2024 edition is now set. Adding individual pages is still possible, but there is not much time to get the Basic Manual ready, which includes Editing, rewriting and cutting down each of the Action/Tasks, and I intend to enjoy some sailing this year!

Next winter we can work on the Advanced Manual and discuss and reorganize the Basic Manual further, if necessary. Sorry, but we have to move forward.

I should note that the new user documentation is contained in "Quick Start". All of the other "tasks", including "Change Options" (or perhaps Change Settings) are used on a regular basis by all users.

Yes, I agree the Tasks need to be short and to the point, and further additional detail should perhaps be moved or put in a sub-page or to "Advanced Users"

The Editor's primary task is now to work on each page that has been moved up one level from TOOL BAR and CHART PANEL and to finish the work in Quick Start.

[leamas]

OK, it's your show. I will not interfere. Stepping out.

[rgleason]

Alec, of course this is your choice. I do wish you would log onto Dokuwiki and help when you can, between all of your (most important programming) and I understand that you prefer asciidoc/antora and the use of github.com for handling changes and github.io for presentation.

I certainly appreciate your advocacy and pushing the manual forward. I believe we are basically like minded about the manual and I hope you will remain an "active board member" guiding this effort!!

Thank you.

[leamas]

Flatpak: I have given the Flatpak FAQ some love, it's now in reasonable shape
https://opencpn.org/wiki/dokuwiki/doku.php?id=opencpn:manual_advanced:program:flatpak_qanda

[rgleason]

Thanks. Looks great.

[torrmundi]

Is there a place to log our progress? Where should I note what I've touched in the manuals?

…

On Sun, Apr 21, 2024 at 11:33 AM Rick Gleason ***@***.***> wrote: Yes please. We need to find a better home for layers. — Reply to this email directly, view it on GitHub <#3820 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU7AEMFNNR6GYMP7S5PO6P3Y6PL6DAVCNFSM6AAAAABGLMDBQCVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TCNZZG44TO> . You are receiving this because you commented.Message ID: ***@***.***>

[rgleason]

Editor Manual -2024 Status and Progress Page

[torrmundi]

Perhaps you could take one section as an example, and split it into a task and a UI reference? John

…

On Sun, Apr 21, 2024 at 2:00 PM leamas ***@***.***> wrote: @KevinKlop <https://github.com/KevinKlop> @Spiv13 <https://github.com/Spiv13> @TwoCanPlugIn <https://github.com/TwoCanPlugIn> ^ Thoughts? — Reply to this email directly, view it on GitHub <#3820 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU7AEMAJV7EFHYNAN7CNS2DY6P5EFAVCNFSM6AAAAABGLMDBQCVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4TCOBQGUZTC> . You are receiving this because you commented.Message ID: ***@***.***>

[ManfredRad]

Finally I am on board here: Aldebaran17 from cruisersforum, Manfred in real live, ManfredRad at github.

A late response to the task or knowledge based manual:

As a novice or starting user, I'd like to see a task oriented intro, which basically is what the Quickstart Manual is.

The real manual could follow the structure of the user interface, since the user interface (mosty) is well structured.

One exception: looks awkward to me to activate "Status Bar Option Live ETA" in Options->Display->General" while the Statusbar is activated in User Interface -> General.

Manfred

[rgleason]

Manfred, I see your point. Can you make an Issue, Pick "RFE" Request for enhancement and follow the prompts.
You should include a small screenshot of both menus, and make your suggestion.
I think this change might be done in the release following this one, but it should be logged as an Issue or it will not be considered.
Thanks.

OpenCPN issue is here https://github.com/OpenCPN/OpenCPN/issues