Clarify scope and common practices of documentation for Tendrl project

[mbukatov]

Right now, we have multiple documentation sources:

• https://github.com/Tendrl/documentation for project wide documentation (asciidoc)
• doc directories with sphinx documentation in each component, eg. https://github.com/Tendrl/common/tree/master/doc/source
• README files in each component, eg. https://github.com/Tendrl/common/blob/master/README.rst

This is good, the sheer number of components in Tendrl requires to have a cross component, project wide documentation as we maintain in https://github.com/Tendrl/documentation, while each project definitely still may need to document details not worth mentioning in the Tendrl wide documentation.

That said, right now the scope is not specified so that we are running into consistency issues such as:

• README file of node agent provides cross component project wide installation instructions at some extend
• there are 2 installation documents in node agent repository, see [documentation] there are 2 descriptions of tendrl-node-agent installation node-agent#89

To maintain some order in this, we need to:

• clarify what scope does the doc component wide documentation have
• if the component should have one
• unify CI checks (to catch breakage of doc build during the pull request)
• actually build the documentation for others to see (and for us to notice invalid references, broken syntax and so on ...), using something like readthedocs
• enforce the rules

[mbukatov]

I'm just point out the issue here, I don't think I'm the right person to draft a solution via new specification pull request.

[brainfunked]

This is a very good point. I'm assigning this to myself. I'll give this a bit of thought and push a specification against this issue which we can then collaborate on.

[mbukatov]

Status update, now we have:

• https://github.com/Tendrl/documentation for project wide documentation (asciidoc)
• https://github.com/Tendrl/documentation/wiki for project wide documentation (markdown)

along with per component README file and docs directories.

So while we have sorted out few details mentioned in the original description from December, some files stalled and the main issue just grown worse in the meantime.

Note that the wiki is most useful and mostly up to date from end user perspective at the time of writing this comment.

[mbukatov]

I will try to describe the current state and draft a proposed simplified guidelines to go forward here: https://github.com/Tendrl/documentation/wiki/Tendrl-Documentation-Scope-Overview

[r0h4n]

@mbukatov Lets work on this further, we need merge the Tendrl/specifications and Tendrl/documentation