CliMetLab documentation structure

[emadehsan]

Hi @floriankrb , would appreciate your thoughts about the structure of CliMetLab documentation and how it can possibly be improved

1. Having Developer Guide > Datasets page when User Guide > Datasets already exists would probably be redundant. Same can be said about Data sources page. Having a single Datasets page describing all the dataset related functionality (available to both User and Developer) might help maintain a single source of truth.

2. Also, I feel that having separate User Guide,Contributor Guide and Developer Guide could be a little confusing and sometimes repetitive? I think that the hierarchy of the documentation would be much simpler and easier to navigate if it is organized with respect to topic (e.g. Plugin, Datasets, Data sources) instead of persona (User > Datasets, Developer > Data Sources, Contributor > Plugins).

[floriankrb]

Thank you for your comments, your PR to have a tutorial makes a lot of sense, I will have a closer look.

The separation per persona is quite fundamental and we would like to keep it because we expect three very different audience to interact with climetlab.

I agree, though that some (many?) parts of the documentation should be moved to the right location. Also, I really like your reference to the Tutorial, How-to, Discussion, Reference categories. Let's make sure that most (every?) item in the documentation is clearly identifiable as one of these four types.

[floriankrb]

And to elaborate on the three main parts in the documentation:

The larger target are the 'User', this is the person using climetlab to with very lines of python (one or two lines). They would use:

• cml.load_dataset(...) quite extensively.
• to_xarray(), to_pandas(), to_whatever() on these datasets.
• cml.load_source(...) with a limited subset of sources ("file", "url", "cds", "mars", maybe some more) and limited subset of parameters.
• cml.plot_map() with limited subset of parameters. The settings should be detailed for them too.

The "Contributor Guide" (a better name could be found) targets the plugin developers. They are expected to use the building blocks provided by climetlab in a plugin, such as the decorators @ normalize @ availability (in progress), and more sources with advanced options.

Documentation dedicated to the developers of the climetlab code itself is currently mostly a set of discussions. This part of the documentation may not be the first priority for now, but it will be as additional core developers are joining. I would also see it as the right place for descriptions of the code (such as the cache mechanism, architecture) would be there.

[emadehsan]

Got it. I appreciate your comments! Now I understand more clearly the docs structuring w.r.t. persona.

Usually all the programmers think of themselves as Developers even while "using" some library. And from a developer's point of view, a user is usually a non-technical beneficiary of a product / software (who doesn't write code).

Most projects on GitHub use the term Contributor to refer to the developer who contributes to the code (and or docs) of a project.

I'm a victim of these conventions. That's why, current structure seemed a bit confusing to me.

May be we can rename these personas to Developer Guide or simply Guide (previously User Guide), Plugin Developer Guide (previously Contributor Guide), Contributor Guide (prevoiusly Developer Guide). Or some other conventional role names that the reader can immeditely relate to.

[floriankrb]

Closing as the documentation is being updated, taking into account these discussions.