Proposal for docs in repo

[haani-niyaz]

Summary

Keep documentation within the repo instead of a remote wiki or Github wiki.

Rationale

From a developer experience perspective, it is easier to clone and have everything you need to reference locally rather than having to externally reference something.

This minimises context switching and aids the practice of keeping documentation updated as it is closer to the codebase.

Solution Proposal

Leverage automatic documentation generation via https://squidfunk.github.io/mkdocs-material.

This integrates well with Github, providing automatic docs for your repo at <username>.github.io/<repository>.

Sample structure:

docs
├── ci
│   ├── gitleaks.md
│   ├── golang-ci.md
│   └── semantic-release.md
└── starter.md # docs on how to get started with this repo

Example:

https://cli.urfave.org/

Generated from ./docs directory: https://github.com/urfave/cli/tree/main/docs

[shukra-in-spirit]

This sounds good. It is a good challenge for someone looking to upskill on ci as there is a lot of document surfing required to create effective reference. The rest of the platform team can provide inputs on the PRs. Please create separate PR for each CI job.

An effective doc should contain:

1. The purpose of that CI (a good reference can be the first paragraph of CI source documentation)
2. What are the requirements of a succesful execution.
3. Simple bug fixes and avoidable mistakes.
4. How to contribute.

[haani-niyaz]

@AlvinKuruvilla I had a play and for this to work it you need to configure the repo otherwise the build also fails. As per the docs:

If the GitHub Page doesn't show up after a few minutes, go to the settings of your repository and ensure that the publishing source branch for your GitHub Page is set to gh-pages.

Required settings:

We'll probably need @shukra-in-spirit to configure this as I don't have access.