Bivouac.com   Document   Home     Help   Index     Login
Help Link Plan #3389
    Date first written: 2016.09.20   Review Date:2016.09.20

Table of Contents
1. Preface
2. Organizing Ideas
3. Insert Trip, Insert Road
4. Download to GPS

1. Preface
The purpose of this plan is to tell you, the senior editor, what it is I'm trying to do with the help. It is a basic plan for how things are supposed to be organized.

This plan covers only the immediate list of "How To" instructions that you see when you click the Help Link. Several years ago, there was also a more widespread plan which covered other things like discussions, documents and so on. But the new plan covers only the items.

2. Organizing Ideas
When you click the Help link, you see a list of "How To" instructions.

  1. Categories
     When you click the "Help" link, you see all the "how to" instructions, sorted under about 10 categories such as "General Website", "Search", "GPS - Upload to Bivouac", etc. These headings are in order from simplest to most complex.

  2. Titles are recognizable
     The titles are written ususally with a verb followed by a noun. Eg: Insert Trip Report. It is assumed that the reader knows what this is. Some of the sections revolve around key objects such as "GPS", GMap, Trip Report. I'm assuming most users know "this is a Gmap question" even if they run into it while trying to insert trip reports.

  3. Duplication
     The basic idea is to have a heading under every expected place someone would search. Eg: If someone has a GPS question, they would expect to find the answer under one of the GPS headings. They may also find some of the same information under a heading like "Trip Reports", but from a different viewpoint.

  4. Factoring
     Some of the complex procedures are factored into several parts. For example, the complete job of inserting a full trip report may involve uploading a raw gpx file from your GPS, using GMap to trace the waypoints, and uploading photos. The GMap instructions are factored out under the GMap Heading, because the same instructions apply both for Trip Reports, Roads and Waypoint Working files.

  5. End Goal versus Component
     Some instructions such as "GMap Draw and Save" may not be immediately recognizable as end goals. Eg: The "end goal" is to insert a trip report, but part of that might refer to "GMap Draw and Save".

  6. Overview then Step by Step
     Every "how to" section starts with a conceptual overview, and then "step by step".

  7. Skeleton strategy
     The strategy for trip reports is to give the person instructions as to how to get a minimal skeleton of a trip report inserted. (Only a title, date, and one waypoint.) That way they have at least completed the cycle, and then they can update all the detail fields such as waypoints.

  8. Progressive Complexity level
     More advanced instructions will be written at a higher "level", assuming that the reader is familar with more basic tasks. Higher level means I assume certain terminology will be understood. For example, I certainly wouldn't spend a lot of time telling someone how to position GMap in my instructions for digitizing roads. By the time someone gets to that level, I assume they know about the different "map views" in GMap, such that you can just say "on the hybrid display you have to zoom into 100m scale to see the road labels. I'm not going to tell them how to zoom in, or that "hybrid display" means "h - Aerial Google Hybrid".

    The overall progression can be imagined as one continuous document to be read from front to back.

    Complete Chronological Tutorial for Authors. I can use this to review the "level" of writing at each stage.

3. Insert Trip, Insert Road
Although getting waypoints for trip reports and roads share many common steps, such as GMap Draw and Save, I decided that the best way to structure it was to separate the Trip Report procedures from the Road Procedures. And also to write separate instructions on whether you use GMap directly, or are downloading trip waypoints from a GPS. Thus there are four "primary" help pages:

Insert Trip Report
  1.1 Get Trip waypoints from Gmap
  1.2 Get Trip waypoints from GPS

Insert Road or Trail
  2.1 Get Road waypoints from GMap
  2.2 Get Road waypoints from GPS

  1. Duplication versus Self Contained
     There is a tradeoff between making instructions self contained and avoiding duplication. In particular, all four of the above involve GMap Draw and save. The strategy I took is to briefly describe using Draw and Save in each case, but also have a link to a detailed "GMap Draw and Save" document. The in-line summary is sufficient that most users will not need to click the link to "Draw and Save" details, because they already know them. This strategy avoids excessive duplication and detail in the primary help pages, but at the same time providing enough description in the primaries that people don't have to click too many links.

  2. Road insert is at a higher level
     The instructions for "Insert Road or Trail" can be written at a higher level, because only experienced editors are involved with inserting new roads and trails.

CASE STUDIES

  1. Author constructing waypoints directly using Gmap
     I was helping a bivouac user Jason put in good waypoints for his trips. I want to send Jason exact instructions on how to do this using draw and save. It was very useful to send him a link to "Get Trip Waypoints from GMap", and thus avoid any confusion with issues that only come up when you are getting points from a GPS. He read the help, and did excellent waypoints.

4. Download to GPS
Downloading bivouac content onto a GPS has three variables:

1. GPS type (Garmin or Smartphone)
  2. Desired Content (Trip, Road, or Mtns)
  3. Gpx link used (Gpx20, Radius Search, or Road plan)

The three things people need to know are:
 - where to find the link and produce the gpx file
 - how to move gpx file so it is accessible from GPS track manager
 - How to use gps track manager

The Standard GPS Operations has the methods for importing Gpx file into every type of GPS. The starting point should be that you have a .gpx file somewhere. So the two halfs are:

1. Produce the gpx file
 2. Load the gpx file into GPS

Therefore Help just needs to tell them how to make gpx files: (but the title refers to the overall goal, and then we have a link to the framework.

PRIMARY INSTRUCTIONS

Download Trip Report (make .gpx file for Trip report)
  Download Roads and Trails (make gpx file with roads and trails)
  Download Mountains (make gpx file with mountains)

A single "Download Roads and Trails" document can tell people about all the different locations of links: gpx20 links, kml links, Radius search, and Road plan.

At present, there is lots of overlap, because the Framework usually starts by telling them to click the gpx20 link, whereas those instructions should be in the Bivouac help.