[netCDF #ZAI-517078]: obtuse direction

Hi Christopher,

> I'm really frustrated with your obtuse documentation.

I sympathize completely, and agree that our documentation has really
gone downhill in some ways with the 4.2 release, which partially
converted documentation from a previous texinfo-based system to a new
doxygen-based system.  The intent was to create better web-based
documents, but there are still lots of problems, as I've documented
here, including some of the problems you've reported:

  https://www.unidata.ucar.edu/jira/browse/NCF-170

> For example: on
> 
> http://www.unidata.ucar.edu/software/netcdf/docs/netcdf_interface.html
> 
> there are instructions to "see Top". What top? In the reference to C++,
> what on the "top" relates to C++? None of the titles on the "buttons" do.
> Why not make that reference to "the Top" a link to the information you're
> directing me to examine.

This was an unnoticed and unfortunate error caused by trying to
automate some of the texinfo to doxygen conversion.  The links that
were in the original texinfo source were inadvertently eliminated, and
should have respectively linked to

  http://www.unidata.ucar.edu/netcdf/docs/netcdf-c.html#Top
  http://www.unidata.ucar.edu/netcdf/docs/netcdf-f77.html#Top
  http://www.unidata.ucar.edu/netcdf/docs/netcdf-f90.html#Top
  http://www.unidata.ucar.edu/netcdf/docs/netcdf-cxx.html#Top

I'm fixed this manually for now, and it will be fixed in the sources for
the next release.

For now, you may want to use the previous texinfo documentation
instead, which is all linked from this page:

  http://www.unidata.ucar.edu/netcdf/docs/index-413.html

For example, the information you seek on what is meant by "record" is
here, in the texinfor-generted Users Guide:

  http://www.unidata.ucar.edu/netcdf/docs/netcdf.html#Dimensions
  
> I'm trying to find out what is meant by a "record" as in the put_rec
> method for NcVar. But your search function within the documentation
> returns no results.

Yes, there's currently an incompatibility between the way doxygen
implements search in the HTML-generated documents and our web site
infrastructure.  For now, I suggest using your browser to search
within the HTML documents in the 4.1.3 documentation.

> In the NcVar method descriptions, you don't really describe what's
> happening.  The "get" and "put" methods don't say how much they're getting
> or setting, and there is an implication that there is a position in the
> data manipulated by the method set_cur that determines where you start in
> the data. Are the other parameters the dimensions of the N-dimensional
> slice you want to get from the current position as set by set_cur? You
> sure don't actually say that. And that's far more complex than the
> simplest explanation. The description of set_cur is missing altogether
> in the version of the library th at I have.

You're right, the C++ documentation needs work.  The old C++
implementation you're looking at is being superseded by a new
contributed C++ API for netCDF-4, which is documented here:

  http://www.unidata.ucar.edu/netcdf/docs/cxx4/

However, that API is still considered experimental until after the
next update.  It's being used and may be adequate for your use, but
the C API is currently the most widely used and best tested API, and
the C++ API is just a thin layer on top of that.

> The warning about reading/writing past the end of the row of data should
> only be made if you've thoroughly described what the LIBRARY is doing. If
> I run off the end of memory I've allocated, that's my problem. If you
> describe well what you're doing, I won't have to divine what it is the
> library is really doing. Well chosen words will save hundreds of hours
> of exploration through foreign code to try to figure it out.
> 
> You've got a great library. Why doesn't the documentation match? A
> couple interns over the summer could make a terrific difference in
> the actual communication of information through your documentation --
> in the headers and separate docs.

Thanks for the suggestions.  Currently we only have 1.75 full-time
equivalent staff working on netCDF development, maintenance,
documentation, and support, so we could certainly use help from summer
interns.

Incidentally, you may find some of the material in our online netCDF
training workshop more useful for some purposes than the current
online documentation:

  http://www.unidata.ucar.edu/netcdf/workshops/2011/

Thanks for reporting the problems!

--Russ

Russ Rew                                         UCAR Unidata Program
address@hidden                      http://www.unidata.ucar.edu



Ticket Details
===================
Ticket ID: ZAI-517078
Department: Support netCDF
Priority: Normal
Status: Closed