Userguide docs general changes

[JohnLCaron]

General issues with the user guide are collected here.

[JohnLCaron]

Im working on bringing

https://docs.unidata.ucar.edu/netcdf-java/current/userguide/dataset_urls.html

up to date in ver7. Its rather big and complex and Id like to restructure it some.

Id like to experiment with adding its own toc, perhaps to a sidebar on the right?.

I assume that the top

---
title: Dataset URLs
last_updated: 2020-04-06
sidebar: userguide_sidebar
toc: false
permalink: dataset_urls.html
---

is for jekyll?

"toc: true" added local toc at the top. Any pointers on how to add to right side?

Also any thoughts on whether thats a good idea? Im often irritated by the site toc on the left, taking up all the real estate, when I want to see the local toc. I had the same problem with docs when I was at Google, they eventually added a local toc on the right.

[haileyajohnson]

(Adding a v7 label so we can separate docs issues by version)

I agree that would help navigate, but I worry that's a pretty big theme change rather than something that makes sense for just a page, but Sean would be the authority on that. Notably, this page has moved from the giant section of "reference docs" to the "CDM datasets" section now - maybe we can split it up into a few more digestible pages?

[JohnLCaron]

What about separating the tutorial files from the reference files in the git layout? I helps me to remember who Im writing for. Reference docs are for developers, they can have lots of arcane details. In a way, I write those to my future self, trying to remember wtf? Tutorial docs are for users, they need to not assume too much and they dont have to explain all the details.

It appears that those are intermingled right now?

Thoughts on a restructured file layout?

[JohnLCaron]

BTW, I see how much work has been put in to try to keep these docs up to date. No easy task as we are going through a lot of change and restructuring. Thanks.

[haileyajohnson]

What about separating the tutorial files from the reference files in the git layout? I helps me to remember who Im writing for. Reference docs are for developers, they can have lots of arcane details. In a way, I write those to my future self, trying to remember wtf? Tutorial docs are for users, they need to not assume too much and they dont have to explain all the details.

Haha, yes, we had the same discussion recently and now have restructured everything (starting at 6.0) into a Userguide (tutorials), a Developer guide (which is right now just a collection of info with no logical flow), and NcML docs. It's much cleaner and similar to the TDS docs makeover, but it certainly still needs a lot of work, and I think a lot of stuff could be split up or removed entirely still so it's not an overwhelmingly large and difficult to read docset.

[JohnLCaron]

Hmmm i see that https://docs.unidata.ucar.edu/netcdf-java/current/userguide/dataset_urls.html is 5.4

Where the 6.0 page?

[JohnLCaron]

I see you have everything in sections under "Tutorial and User Guide". Ill look over that to see how it feels.

1. Should there be a different "Reference section" as I described it?
2. How should the files be laid out in the git repo?

[JohnLCaron]

Perhaps the developer pages should be directly on github?

So Unidata is value adding the user guide?

[lesserwhirls]

There is sort of a top level listing of documentation on the docs site:

https://docs.unidata.ucar.edu/netcdf-java/

We're working on a little CSS to make it more pretty, but for now, it works. There is a version selector widget at the top left corner of the docs page, so that you can switch between versions of a page easily.

It's...a work in progress, but 5.4.1, 6.0, 7.0, and current should work. I'm backporting the theme to other 5.x version so that it all looks the same and has the same functionality. The dataset urls page lives here: https://docs.unidata.ucar.edu/netcdf-java/6.0/userguide/dataset_urls.html.

Starting with 6.0, we have three docsets like @haileyajohnson mentioned:

1. Tutorial and User Guide: https://docs.unidata.ucar.edu/netcdf-java/6.0/userguide/index.html
2. NetCDF-Java Developer Documentation: https://docs.unidata.ucar.edu/netcdf-java/6.0/developer/index.html
3. NcML: https://docs.unidata.ucar.edu/thredds/ncml/current/index.html

My thinking is that NcML is used/implemented in places other than netCDF-Java, so we broke out the NcML stuff into its own docset. One day (maybe soon) I could see the xsd and associated documentation could live in its own repo, and the netCDF-Java and TDS docs reference that as needed. Same for the THREDDS Client Catalog spec, just to further hammer home the point that THREDDS client catalogs != netCDF-Java only (a sadly common misconception).

The developers docs used to be what we called the the reference docs in 4.x. I have wondered if the developer/reference docs should live on the project wiki, but I've hesitated on that as there are important things that apply to 5.x, but not necessarily >=6.x, that still fit the category of developer/reference docs (or both, but the implementation differs between the versions). That makes documenting those things on the wiki tricky, but possible.

We take the markdown files and organize them into one or more HTML docsets using Jekyll. Jekyll does not look at the directory layout so much when constructing the URLs, for example - Jekyll looks at the front matter in the markdown file and uses the permlink to name the generated HTML.

[JohnLCaron]

Instead of using the github wiki, we could just use markdown pages linked from the readme; then its versioned. Its what Im doing on my other project. basic, but github keeps adding features i havenet explored.

[JohnLCaron]

Ok, ill start looking over the above docsets. I couldnt find the latter two from the landing page https://www.unidata.ucar.edu/software/netcdf-java/