Tendrl/documentation

Tendrl Documentation Recommendations

julienlim opened this issue · 2 comments

julienlim commented

The Tendrl repo should have easily accessible user-facing documents that are easily maintainable / editable via GitHub to enable community contributions (e.g. MkDocs-like which is also what Gluster uses for their docs), and accessible from the Tendrl GitHub repo and Tendrl website.

Consider a repo for tendrl-docs to include the following:

  • Getting Started & Install Guide which should include Performance and Sizing Guidelines
  • Release Notes
  • Administration / User Guide
  • Troubleshooting Guide
  • Developer’s / Contributor’s Guide
  • Upgrade Guide
  • Glossary

@Tendrl/specs @Tendrl/qe @Tendrl/frontend @Tendrl/docs

mbukatov commented

I would suggest to either switch to rst sphinx (read the docs) project or asciidoc asciidoctor project.

The 1st one could be easily setup on readthedocs site, for the latter, we would need to make a CentOS CI building job.

I would vote against whatever gluster.org project is using right now, as I consider it quite terrible (markdown hacked into read the docs like project template).

Back in January this year, I discussed this with Rohan and we concluded that the 1st step could be to move the documentation completely to the wiki and then use either sphinx or asciidoctor project.