[objective] Strong Documentation

[viega]

We've definitely written a lot of documentation so far, and think it's important for docs to be easy to find and understandable. We also think there need to be both sufficient reference-style docs, and sufficient task-oriented docs (tutorials and how-tos).

And, we want to minimize outdated documentation. In the code, we have tried to make that task more manageable for user docs by keeping docs inline next to the config options and flags.

Unfortunately, as I write this, we're completely lacking in developer documentation. Yet, Chalk is actually a fairly sizable project, to the point where code plus comments is nowhere near enough to help make it easy for people to contribute.

The people who contribute will undoubtedly want to understand the "lay of the land" so to speak, meaning that they'll want to have a reasonable understanding of the architecture, and how they would plug into it.

Some reference documentation would be valuable, but it will be more important for people to have task-oriented how-to guides to tackle the enhancements they're most likely to want to make.

At the very least, we should probably have clear guidance on:

• How to support adding new metadata sources of various kinds. Beyond the logistics of it in NIM and/or con4m, we need to discuss the non-Nim API. Additionally, we need to help people understand how to think about the existing metadata keys, vs. new ones.
• The approach / processes for integrating third party SAST / SBOM tools.
• How to add support for chalking new types of artifacts, if people want to help tackle things we haven't gotten to yet, like Windows binaries, in-browser code, etc.
• How to add new output sinks, for instance, for other cloud object storage, databases, etc.
• An explainer for the attestation code, and a sense of where to start if looking to extend (either by adding integration to other external secret managers, or by moving the Sigstore integration internally).

All of the above will need to be supported by an overview on how to work with the config files.