RFC better documentation structure

[tiborsimko]

Now that we have started to finalise the Invenio 3 beta documentation, the time has come to improve the documentation structure. I would propose the following changes:

Always visible menu. Currently, the lhs menu collapses when you click on say one API Docs section. This can lead to cryptic pages where the reader may feel lost. Besides, we don't have many nested chapters, so the menu can stay "always-visible". This eases the navigation. We already use it in Invenio documentation, e.g. technology docs example. Let's do similar for packages' menu too. Another good example of what I have in mind is SQLAlchemy-Continuum, among others.

Introduce Features section. The casual reader coming to an Invenio-Foo page would need a short introduction about what this package does. We say it in one phrase in the beginning, but it would be good to standardise this across packages. Basically, we can have a short "Features" heading with one-phase mission statement and an itemised list stating the main features as bullet points. This can be part of the home page.

Introduce Configuration section. After people learn what the package does, they may want to learn how to configure its behaviour. It would be useful to have a "Configuration" documenting all configuration variables.

Streamline User Guide. The User Guide is good, but the "Installation" section does not seem to really make sense as a separate page. It is too short and can be covered easily as part of the User Guide tutorial. Besides, people will be installing most packages as dependencies via over-arching Invenio "flavours". If they need to see the pip installation command explained, they are perhaps wrong audience.

Use Getting started? The "user" guide is often a "developer" guide, as it were, so what about renaming the tutorial to something like "Getting started"? Packaging the example app as part of such as getting-started tutorial would make sense. Then add other sections as need be for "bigger" packages.

CLI reference? What about a new CLI reference section where we document all the available CLI commands and options?

API reference. Nice, let's simply complete the sphinx autodoc, add :param, :returns, :raises, etc as appropriate. What about signals?

Simplify Contributing. It is long, and may be somewhat misleading, e.g. "Get Started!" heading is for developers only, since the bug reporters already "got started" before. I'd rather simplify this page, make it very short, and point to the centralised Invenio docs

WDYT? I can prepare an example PR to provide an explicit example.

CC @inveniosoftware/triagers

P.S. See also parts of inveniosoftware/invenio#1799

[lnielsen]

Always visible menu.
+1

Introduce Features section.
+1

Introduce Configuration section.
+1

Streamline User Guide. The User Guide is good, but the "Installation" section does not seem to really make sense as a separate page.
+1

Use Getting started? The "user" guide is often a "developer" guide, as it were, so what about renaming the tutorial to something like "Getting started"?
+1

Packaging the example app as part of such as getting-started tutorial would make sense. Then add other sections as need be for "bigger" packages.

This I think could potentially be quite some work. I see the getting started section as a quick introduction to the basic programatic API of the package the concepts of the package.

CLI reference? What about a new CLI reference section where we document all the available CLI commands and options?

When it makes sense +1, but I find it more important to document e.g. the REST API. CLI should be self-documenting as much as possible via --help.

API reference. Nice, let's simply complete the sphinx autodoc, add :param, :returns, :raises, etc as appropriate. What about signals?

+1 Signals as well.

Simplify Contributing.
+1, but linking to the centralised Invenio docs I think is complicating it instead of simplifying it. The central docs are very long and detailed, which can be good for extra details, but we need a short concise "contributing guide" that new contributors can quickly look over to get the most important points.