Integrate manual to hero tool with uniform documentation process

[Mik-TF]

In brief: Devs write basic docs with the essential infos in their current working repos, then the communication team can upgrade the docs on the repo itself to fit the manual/end-user version, then we set hero tool to link the docs to the manual. This kind of docs would be easier to maintain and it could free lots of time on the dev side. Devs would have a clear view of the docs used outside of their own repo (e.g. in the manual) and could accept the PRs of the docs directly on their current repo. To facilitate the hero implementation, we suggest that all docs files are within repo_name/docs

Proposition: Integrate manual to hero tool with uniform documentation process

Situation

There is a new hero tool, see code here and related issue here, which can be used to create and organize mdbooks.

This is being used to collect many different mdbooks created by ThreeFold.

Proposition

We should check how to integrate the manual with the hero tool. Not only this, but we should make sure we develop an efficient, uniformed and reproducible method to create documentation for ThreeFold Tech. If done properly, this mean that we could save time by only working on one set of documentation, and it would ensure that the content stays relevant (no outdated information).

For example, as of now if we write a text on, say, TFROBOT, and that the devs maintainting the TFROBOT repository on github change the code and/or the documentation, this wouldn't be reflected in the manual (info_grid repo) version of the documentation.

We thus propose to create the documentation directly on the related repositories, and to build the manual from a summary.md file containing links to all the different repositories documentation.

Benefits for Developers

This process ensures that developers can easily keep an eye on the documentation built and distributed since the documentation on the mdbooks comes directly from their repositories. They would have to accept pull requests updating or creating documentation based on their code.

Method for Docs Creation

We propose that every repository has a docs section, where the documentation would be organized in a constant manner, as to create easily mdbooks from this. Note that most of the TFTECH repos already are working with a docs folder. It's just about organizing further the documentation process.

This means that each repo can still have a general readme.md documentation for the developers using the repository while the docs folder contains the information to be shared on any TF (md)books.

Proposed tree

We propose that the documentation follows the template on the manual, this ensures a uniform presentation in all TF books.

The docs folder tree could be as follows:

• One page documentation
  • all information on one page
  • docs/readme.md
• Multiple pages
  • one page for the TOC, the rest organized in sub-directories if necessary.
  • docs/readme.md
  • contains TOC

This means that users could also consult the documentation directly on the repository, or on the TF mdbooks.

Functioning

Let's take the TF manual as an example. For the info_grid manual, we create a summary.md file where we link to all the different repositories docs' folder.

If there is an update in the product itself (e.g. TFROBOT tftech repo), we can upgrade the documentation directly on the repository and it will be reflected on the repo AND the manual.

Future Use with Example

In the future, when we get issues on creating or updating documentation, we could add the related docs URL to the summary.md and then create/update the content directly on the related repository.

Feedback

This is a proposition. One could argue that it's better to keep the manual organized as is, by writing articles for each section without using the hero tool. IMO, it's clearly simpler in the short-term to keep the actual manual organization, but using hero cli will be more efficient in the long-term.

There might be better ways to proceed.

[Mik-TF]

Started documenting and testing the tool:

https://git.ourworld.tf/tfgrid/info_tfgrid

see docs and scripts

[xmonader]

I don't get the suggestion, even the tool itself i don't get what it does.

[Mik-TF]

I understand, as there is few docs on this.

In short, how it can be used with mdbook, is that you use the hero tool to take markdown files from different repositories on github, and you can build a custom-made mdbook out of this, and host it on a website.

So for example, say we want an mdbook with tfrobot, tfcmd and farmerbot. Instead of taking the docs from those repos, and putting them on the info_grid repo, then adjust as needed, we can just use hero tool to "point" to the docs within the tfrobot, tfcmd and farmerbot repo themselves, then build the mdbook.

So it's like a way to use docs on different repos instead of bringing them under one repo.

The issue with the current model is that when changes are brought to the original repos (here tfrobot,tfcmd and farmerbot), it does not reflect on the info_grid repo. So we are always chasing new updates.

EDIT: We might decide not to use the hero tool. It's a suggestion.

[Mik-TF]

Closing this issue as hero will be worked on elsewhere as discussed with KDS.