Documentation generation

[azabujuban]

What are the current best practices for documenting the various resources, pipelines, etc... for tekton? Of course one way is to have it in a readme or similar, but wouldn't it be better to add annotations inline in the yaml files and generate the docs automatically?