README revamp ideas

[tazjin]

Documentation is a hard problem. How do you make features discoverable to users when they need them?

Currently this isn't solved well in the documentation that the repository has, but I'm thinking that a revamp of the README (which is probably the documentation entrypoint for most people) can partially solve this.

One idea I had was to start off the README with a list of features, each of which are a link to a more specific documentation piece for that feature. For example:

Kontemplate is [... blabla ...]. Check out an example and the feature list below:

[simple usage example]

## Features:

* [Simple, yet powerful templates](docs/templates.md)
* [Clean cluster configuration files](docs/cluster-config.md)
* [Integration with `pass`](docs/pass.md)
* [Integration with `kubectl`](docs/cli.md)
* ... other stuff

## Best practices

Kontemplate is being used in several real-world Kubernetes deployments.

Check out the best practice documentation on [code organisation](docs/code-organisation.md) and [CI integration](docs/ci-integration.md).

The one thing that is still missing here is something that communicates the term resource set clearly to the user. Ideally there would also be a link to an example project that makes use of as many features as possible (*sigh* I should update all my tazj.in things).

[tazjin]

Alternatively:

Kontemplate is [...]

[simple usage example]

## Getting started

There are two ways to get started with kontemplate.

1. Read the [quick-start guide](docs/quick-start.md) and check out the [feature list](<anchor to feature list>) to learn about all the functionality in kontemplate.

2. Check out the [example project](https://git.tazj.in/tazjin/infrastructure) which attempts to make use of most kontemplate features. Templates and context files in the example project are documented.

---

This would require a few other things to be created first:

• Quick start guide with a basic "How to find your kubectl context, bootstrap the context file, deploy a simple resource"
• Documentation for individual features (which require docs?)
• An example project, probably based on my tazj.in configuration to have a real-world example. The question is whether it should be "runnable" or not? The example project could also be an extended version of the deployment from the quick-start with extensive commenting inline.