EPIC: Improve End User documentation for OCM CLI

[robertwol]

Description:

As an end user of the OCM CLI, I want the documentation to be clear, concise, and user-friendly, providing a comprehensive understanding of OCM-related terms and concepts. The documentation should include concrete examples and avoid excessive complexity to help users grasp the core concepts easily. Avoid academic language and focus on clarity

The documentation should be accessible in different ways and formats:

1. Help text provided when executing ocm |<verb>|<object> --help.

• should follow best-practices from other CLIs, like kubectl or helm
• should only contain
  • rough, but enough (!!!) description
  • examples
  • available (sub-) commands
  • flags
• extensive and lengthy text must be avoided

2. Help text provided in form of a man page. The current CLI reference documentation available using ocm --help (which is the same as used on the web page: https://ocm.software/docs/cli-reference/) comes from https://github.com/open-component-model/ocm/tree/main/docs/reference. From a content perspective this is basically what should go into a manpage.

• should contain more extensive command documentation, very similar to what. the current help texts cover
• should have the standard Linux man page format
• check https://carlosbecker.com/posts/golang-completions-cobra/

3. Documentation on the web page.

• should have an introduction section for OCM key concepts at the beginning, that also explains where OCM has advantages to other solutions and can bring real benefit. As example the Kargo project may be useful: https://docs.kargo.io/concepts
• should explain the usage of the OCM CLI with real-life examples, covering the most basic commands in an end-2-end scenario
  • create ctf
  • add cv to rtf
  • get cv
  • transfer cv
  • download resources from cv

Definition of Done:

• There is short, precise, helpful and easy to understand help text available for every command and subcommand.
• There is a man page available that - in addition to a combination of all help texts - gives extensive explanation of all (sub) commands
• There is a document on the website available that explains the usage of the OCM CLI using examples for the basic commands required to fulfil the end-2-end scenario: create and inspect CV, transfer CV, download resources from CV
• The documentation has been simplified and condensed, removing unnecessary details while maintaining clarity.
• Academic-style sections of the documentation have been restructured to communicate the core concepts in an accessible manner.
• The revised documentation has been reviewed and validated by end users for clarity and usability.

[morri-son]

https://carlosbecker.com/posts/golang-completions-cobra/ for the creation of manpages using mango and cobra: