Need to improve documentation for ncgeodataset users

[GoogleCodeExporter]

We need to improve the documentation for the user of NCTOOLBOX using 
ncgeodataset.  

The quick examples on the landing page under "it's simple" are great.

Under Documentation, we have a "quick start", which has a link to a tutorial on 
reading data with ncgeodataset:
http://code.google.com/p/nctoolbox/wiki/UsingNcgeodataset

The problem is that this page is really quite incomplete, and much of what a 
ncgeodataset user would need are found on parts of:
http://code.google.com/p/nctoolbox/wiki/ncgeodataset
http://code.google.com/p/nctoolbox/wiki/ncgeovariable
http://code.google.com/p/nctoolbox/wiki/NewChangesToNctoolbox  (curly brace 
syntax)
http://code.google.com/p/nctoolbox/wiki/NctoolboxUtilityFunctions

I thought I remembered putting in a fair amount of time at some point trying to 
improve a tutorial, but perhaps I dreamt it, or never saved it.

Alex or Brian, do you have a vision for what the documentation should look like?

I'm really a bit confused.  But if you guys are confused too, I can take a stab 
at trying to figure out something that might be reasonable.

-Rich

Original issue reported on code.google.com by rsignell on 28 Oct 2011 at 12:10

[GoogleCodeExporter]

The answer is really that the toolbox is complicated. But ill work on 
consolidating things into a more concise tutorial in UsingNcgeodataset

Original comment by crosb...@gmail.com on 28 Oct 2011 at 5:23

• Changed state: Started

[GoogleCodeExporter]

How does UsingNcgeodataset look now for a first cut?

Original comment by crosb...@gmail.com on 31 Oct 2011 at 3:42

[GoogleCodeExporter]

My recommendation ...

Create some demos (i.e. m-files in the demo directory). Each demo should be 
short, clear and illustrate a single feature of or use case of ncgeodataset. 
Successive demos, can build on previous ones and become a little more 
sophisticated. That way users can run and try out code to see exactly what it 
does. You might even want to call them 'geodemo1' 'geodemo2, etc, to 
distinguish them from the existing demo; or maybe 'geodemo1_readmeatadata', 
geodemo2_plotunstructuredgrid'. Don't be afraid of long descriptive names, but 
you should name them so the users know they are looking at demos. Using demo 
names like 'readmetadata', 'plotunstructured' will confuse users, they won't 
know what's a demo and what's a support function.

Original comment by bschlin...@gmail.com on 31 Oct 2011 at 3:58

[GoogleCodeExporter]

p.s. Regarding http://code.google.com/p/nctoolbox/wiki/UsingNcgeodataset

DISCLAIMER: Criticisms to follow ... I don't mean to sound harsh but it's early 
on a Monday and my coffee hasn't kicked in yet. I still love you guys.

Take a look at your headings. The top of the page has the following:
NCGEODATASET CLASS
  First thing to do:
    Method 1
    Method 2

The term 'class' doesn't mean anything to most Matlab users; you're now scaring 
your users. The other headers don't tell anyone anything; they have to actually 
read the fine text to see what the content is. The user should be able to 
browse the headers to find the information section they're looking for.

The sections need to be small and tight. The following format is great:
Descriptive header (Tell's me what the section is about)
  Descriptive subheader (if needed)
    Code snipped (shows me how to do what the header is saying)
    Brief discussion of code. Short and concise. If I have to scroll to see all the text under a subheader then it's too long and should be broken up into different topics. If you wrote a demo that illustrates a topic, provide a link to that demo in the Mercurial repository.

Also, please avoid statements such as "This first way to access data is the 
syntax preferred by the developer of this part of nctoolbox. ". If there is a 
method that's exposed that your users shouldn't use then don't document it. Or 
document it with, "Don't use this". Otherwise, it's up to the user to decide 
what's preferred. The Docs just provide the facts, we should withhold our own 
opinions.

Hey, criticism is fun!! Cheers

Original comment by bschlin...@gmail.com on 31 Oct 2011 at 4:15

[GoogleCodeExporter]

How do you refer to a class without saying class? object/variable? 

Rich wanted me to do a complete example of the same thing for each of the 
different ways to do it, how do we structure it better? This part is NOT 
intended to be a quick reference and we were intentionally trying to avoid the 
small and tight reference style of all of the other pages. Perhaps we should 
move it to a different page, but I think Rich wanted it to be UsingNcgeodataset 
since that is the link that we point to as a starting point in other parts of 
the documentation.

Original comment by crosb...@gmail.com on 31 Oct 2011 at 4:59

[GoogleCodeExporter]

"How do you refer to a class without saying class? object/variable?"

Use something descriptive, like "ncgeodataset in Depth".

At the top you should explain why ncgeodataset is special, give a brief 
overview of what the users can do with it?

"This part is NOT intended to be a quick reference and we were intentionally 
trying to avoid the small and tight reference style"

That's fine. But you should have a link to the basics at the top; so if a user 
lands on this page and gets in over their head, they can easily find what the 
simpler stuff.  For detailed docs, I still very strongly think you should still 
break it up into clear, tight sections. For example:

Instead of "First thing to do:" use something like "Working with gridded 
geographic data" (or whatever appropriately describes the section.
<Overview of what the section is about>  We'll illustrate a few techniques on 
how to read and use gridded data. The examples below will show you how to read 
and plot salinity stored in a mercator projected grid. blah blah blah

Instead of 'Method 1' => Reading grid data using 'grid_interop' (or something 
like that)
<Overview of what the section is about> Explain why grid_interop is so awesome. 
What's the advantage to the users of using it?
... 

Be mindful of excess verbage (i.e. Sedulously eschew obfuscatory hyperverbosity 
and prolixity.) For example: "In this example we create a geovariable object 
from the salt variable in this dataset. This is done by calling geovariable 
with the name of the netcdf variable we are interested in as an argument." 
could be shortened to "First, create a salt geovariable"; the code example is 
sufficient to show the how. 

my 2 cents

Original comment by bschlin...@gmail.com on 31 Oct 2011 at 5:33

[GoogleCodeExporter]

Love criticism.  Keep it coming!
@Alex: I think Brian has good points here.  Our problem is that we've got 
multiple awesome ways to access the data:  one awesome way lets you have the 
full power of the toolbox via objects and methods, and another awesome way is 
using higher level routines that let you have limited power but sometimes let 
you do what you need to do in only one line (nj_subsetGrid to subset bathymetry 
or remote sensing imagery, for example).

I like the idea of the geo_demos.  The first one could be just subsetting 
bathymetry. The next one extracting and subsetting RTOFS data using geosubset, 
then you could add your examples of reading time profiler data, etc.

Original comment by rsignell on 1 Nov 2011 at 11:08

[GoogleCodeExporter]

How should we structure the docs to allow for these tutorials though?

Original comment by crosb...@gmail.com on 1 Nov 2011 at 3:25

[GoogleCodeExporter]

The docs don't necessarily have to follow the demos. But I would write some of 
the demos first ... they'll give you a better idea of what  a user needs to 
know to accomplish a specific task. That'll give you a better idea of how to 
structure the docs.

Original comment by bschlin...@gmail.com on 1 Nov 2011 at 3:35

[GoogleCodeExporter]

Beginning to add Matlab published versions of the demos, so that they can be 
used as documentation locally or on the google code site. These can be found in 
the 'html' folder on the level of the demos.

Original comment by crosb...@gmail.com on 17 Apr 2012 at 6:43