Plan for documentation

[filmaj]

I've been looking at ways of improving the documentation for this project (i.e. #166) and just recently stumbled upon the README that exists under the docker/ subdirectory. Cool! Also noticed that there is auto-generated docs under the doc/ dir. Nice!

TL;DR I think we need to consolidate the docs a little bit, between the various doc locations in this repo, as well as the tutorial repo.

Between the docs under the subdirectories, and the README, I feel like we're getting a bit lost. It would be nice to converge on a single approach.

I personally am a fan of immediate, getting-started type stuff being documented in the README. Things like requirements (needed dependencies, accounts that need to be setup), a quickstart-style usage guide, and how to run the tests are all things I think every project should put in a README.

But then the README-in-a-subdir approach that the docker/ subdir has taken, vs. a single top-level docs/ directory, are approaches that I think are against each other. I think we should choose one.

As an aside, I like the fact that detailed config documentation is auto-generated and the docs live with the code. That is great. Perhaps we could even add some automation to the CI in this project to generate that code on every push to master and publish it to e.g. this project's github page? Perhaps long-term we could document mordred's API as well and publish an API reference? This kind of documentation feels very specific to this project, so I think this information living within the repo (or on this repo's GitHub Pages) makes sense.

It feels like having documentation that is specific around Docker for this project makes sense and is needed as this project is the keystone piece when it comes to the grimoirelab docker container. But does it make sense for the docker/ subdir to have its own README? Maybe. Or maybe some of that information belongs in the docker guide that is part of the grimoirelab tutorial? The main sections I see in the current docker/README are:

• The different configuration and setup files mordred uses, feels like it could belong in the top-level README if we could condense it down. OR, we could move that to a guide in the tutorial under Mordred? I think I prefer the latter option.
• I believe we already have tutorial documentation around the projects.json file. If so, we should simply link to that and avoid duplicating our documentation.
• im not super familiar how docker-compose.yml fits in. but is this still needed?
• again not clear to me what the advanced features are about but sounds like this could be better served as a tutorial guide

Let me know your thoughts! I know it's a lot to take in but I think these kinds of writeups from someone like me, a newcomer with no context around how a lot of this stuff works, can be helpful to smooth out the contribution process and therefore scale the development of GrimoireLab up by getting more committers and contributors involved! As always I am happy to send pull requests with ideas on how we could change stuff, or implementations of ideas that come out of this conversation.

Cheers, Fil

[canasdiaz]

I do agree with most of your comments @filmaj. The fact that we have a README in the docker directory make things less clear, my proposal about this is to move the docker logic to a new repo (just for the Docker container). This way the tool is not dependent on a container and the documentation gets simpler.