1.9 Improve Documentation for docker deployment

[abhi4578]

Maintain uniform structure, git version documentation just like a code, mainly because docs will change with code changes and releases!

Structure the documentation , according to needs

• How to install guide
• docker. docker swarm starter
• Also includes overview configuration details for backend components
• Documentation of each components - config, settings, and how to deploy
• Design decisions, reasoning

[abhi4578]

Documentation and Hosting

• Maintain uniform structure

• Version documentation - use git , mainly because docs will change with code changes and releases!

• Anyone ( not just us from the team) can edit documentation or suggest changes, one more reason for using git

• Availability at one place in git , preferably developer guide, how to install guide, Architectural overview etc. @swaminathanvasanth

• the documentation on oss project should itself be open source in true sense!!!, one more reason for using git

• host using github pages/readthedocs, github wiki, jekyll etc..,

• Examples

  • Docker docs src code , https://docs.docker.com/
  • kubespray docs src code, https://kubespray.io/
  • kuberentes docs src, https://kubernetes.io/docs/home/
  • loki docs src, https://grafana.com/docs/loki/latest/

  Feel free to extend this discussion here on this thread at everyone in datakaveri team

[abhi4578]

The markdown docs can be "beautified"/UX or UI themes through some sort of static site generator from markdown files(.md) , in docker they use jekyll static site generator. Its OSS licensed under MIT. Host it using github pages?

[abhi4578]

Its pretty much simple both for UI point of view and developers/anyone who wants to contribute to documentation by just clicking edit docs
. Its standard template markdown and edit the markdown files! The src markdown file
https://github.com/docker/docker.github.io/blob/master/get-started/overview.md corresponds to docs page is https://docs.docker.com/get-docker/! You can get much better idea of each page by going to that page in docker docs and clicking edit this page which would redirect to exact github src code of that page :)

[abhi4578]

• Nice video summarizing hosting of docs on github pages using jekyll for creating more custom UX/UI
• How to host jekyll generated site on github pages refer

[abhi4578]

Pros of hosting docs on github pages using jekyll:

• Free hosting and automated deployment on github
• No server maintainence
• All content is git versioned
• Not much programming involved apart from themes, UX/UI, most of the content in markdown files
• No security wholes and worries
• jekyll simple to understand
• Custom domain support and free ssl certificate when hosting on github
• Can embed youtube videos

Cons:

• fewer themes and plugins
• search is weak
• Not so good for large binary files - pdfs, images --> might have to be compressed
• No server-side scripting (e.g. contact forms).
• Content cannot be dynamically presented (e.g. based on popularity).
• versioned documentation - maybe not so straightforward as sphix/mkdocs in readthedocs . Reference 3.

References:

1. https://ericnish.io/blog/jekyll-pros-and-cons/
2. https://idratherbewriting.com/2015/11/17/pros-and-cons-of-jekyll-for-docs/#2-you-can-make-beautiful-sites-teaming-up-with-ux
3. https://justwriteclick.com/2017/07/30/investigating-jekyll-for-versioned-content/

[abhi4578]

It would be better if we know what exact content is to be hosted through website and other requirements of website -

• is it just docs?
• any youtube videos?
• lot of images?
• what use cases?
• how much UI/UX is needed?
• how much (size) content will it serve?
• who are the users of this "portal"?

[abhi4578]

versioned documentation - maybe not so straightforward as sphix/mkdocs in readthedocs . https://justwriteclick.com/2017/07/30/investigating-jekyll-for-versioned-content/

[abhi4578]

Some requirements from the meet on friday 12 Nov on documentation tool, how we start documenting:

0. Easier to contribute to docs by each team and should not be concentrated to a specific team
1. Use of markdown files for docs and host using some sort of static/docs generator which would generate docs in good UI/UX way.
2. Have as little customization as possible in Markdown files related to the tool we use for genera

tion of docs from markdown files. Eg: minimize use of liquid template in md files if we use jekyll tool
3. The Docs itself be open-source so if any documentation is missing, it can be contributed by the community or create issue for adding that docs through github.
4. Having some sort of versioned documentation in the generated docs possible, would also be good! If we are planning to support atleast one or more versions! eg: in https://kubernetes.io,
5. Able to host it easily and deploy changes easily. Automation would be good.
6. The tool must be able to fulfill whatever UX/UI designs we get in a simple manner

Please add more if i have forgotten something @mahimatics @ThorodanBrom @swaminathanvasanth @abhisekparichha-iudx @Rnaaz @kailash @rraks
Feel free to discuss here the tools in this issue thread!

[Rnaaz]

Docusaurus is another powerful open source static-site generator which can help to build a beautiful documentation site in no time. It builds a single-page application with a fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features, but can also be used to create any kind of site.
Some of it's key features:

1. It uses Markdown files for editing.
2. Uses advanced features like versioning, i18n, search and theme customizations.
3. It can be easily deployed using netlify or github pages.
4. It uses yarn to build the application, so it's very fast while updating or modifying the files.

Sharing the links for the above. Please feel free to share your views & feedback.

https://docusaurus.io/docs
https://www.youtube.com/watch?v=I-hYKNgaMmE
https://docusaurus.io/

Also sharing the screenshots which I have edited using Docusaurus.