documentation practices

• user comments are especially invited
• how changing URLs are handled

A good way for users to help in oce development is to comment upon deficiencies found in the documentation for its functions. Although the R packaging system ensures that documentation and code match reasonably well (e.g. packages will not build if the arguments to functions are stated differently in code and documentation), there are several ways for documentation to be weak. Sometimes, it's a matter of rushed writing. Other times, a function changes and the documentation is changed locally, without the developer reading the whole function description to see if it still makes sense.

When a user is considering whether to report an issue with documentation, the best guide may be to ask whether clarifying the documentation would likely help another user. If so, please be generous and suggest changes.

Please bear in mind that specific comments tend to be more helpful than general ones. "I don't understand the documentation for this function" is less useful than "please state the unit for this variable". Context is also important: it is not the place of oce documentation to explain the nature of oceanographic instrumentation or how to use R.

Some functions are documented using Roxygen2 (i.e. using comments in the R/*.R code) and others are documented in hand-written man/.Rd files. The former always contain a comment at the start warning developers not to edit them.