Docs organization ideas from community

[jcfilben]

Moved this issue from Grommet repo. Original issue: grommet/grommet#3361

This is a very general proposal for Grommet docs approach:

Docs Scaffolding
A proposal on how to structure the Grommet docs.

Docs aim at serving the following audiences:

Evaluators
These are people, not necessarily technical, who seek general information on Grommet maybe because they are evaluating adoption, or because they are writing an article to be published ("The World 2 top React UI frameworks"), or just because.
Newbie devs
These are devs who are just starting to use Grommet in their work.
This audience needs concise, precise, information on the API, ideally liked to more explicative articles focused on the subject where the link was taken.
Techie devs
Albeit the combination of API docs and explicative articles should be enough for everybody, some users are more hardcore techies that want to go deeper and would like, for example, to browse the code in order to understand how it works.
Serving this group is important because it's the source of new contributors, and the better we serve them the faster they are productive.
These users might want to consume a set of articles explaining the software architecture, design goals, … Also coding conventions, guidelines and formats. Build process.
As an example, think of the theme.

An evaluator needs to learn that there is a theme that rules the appearance of the Grommetized UIs, and that it is possible to impact the whole application with maintenance changes of the theme, no need to go in a screen-by-screen process.
A newbie needs to understand how to bring up an initial theme, how to apply it to the components tree, and where to look for information on the theme defs.
That there are concepts like the color object that are to be applied ~ everywhere.
A techie might be happy if pointed to the themes repo by an article about the utils used in the building process. For example
https://raw.githubusercontent.com/grommet/grommet/master/src/js/themes/base.js
Notice that this is independent of the tool used to publish the API contract.

meta: After discussing this and agreeing on an approach, then the next steps suggested can be:
1- to build the scaffolding, that is, a hierarchical index tree of all the docs whether we already have them or not,
2- agree on the tree (the branch names will be chapter or article names visible from outside),
3- pin each article (existing or new) to the branch (or branches) where it belongs, perhaps chopping it in pieces each one suitable for a different branch, and
4- obsessively link each mention of something else to its own article.
The steps are not to be serially completed. After some initial effort, they will be developing along time.
The tree branches will have names, but this is not enough: many will require criteria definitions to pin an article there.

What & how
We developers have developed a skill to understand how things (mechanisms, programs, …) work and this is our way to understand the world.
We think that this is normal, and it is. Only not everybody needs or has developed such skills.
Actually, developer or not, when approaching a software tool we plan to use, we need to understand what will be able to achieve with that tool, if its outcomes are aligned with our goals or not.
This means that, instead of start explaining how it does it, we should firstly tell what it does.
Then for the reader it's much easier to gradually grok how each step contributes to the final goal, that is known in advance.

Additional comment:

Now I would like to point to Diátaxis, "A systematic framework for
technical documentation authoring"
https://diataxis.fr/
It is not a tool (as the word "framework" suggests) but a logical approach
for those who want to design the documentation of something like Grommet.
It is something like my original proposal at the top of this thread, only
better done.