chore: Reworked CLI conventions and include more details

[rhuss]

This PR tries to add some more details about the CLI conventions that we have established for the kn client. This guideline should also apply for plugin development.

[mattmoor]

Produced via:
prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github | grep -v docs/cmd/)

[maximilien]

Left some comments. Overall OK and could use some examples early on as are provided toward the end. I also think we should address:

1. plurals of names. So kn services create ... should be OK and same kn service create ... Like kubectl
2. putting verb before resource names. So I would also be in favor of kn create service ... to be same as kn service create ...

If there is an issue open for these, then just list the issue until resolution.

Please also address the auto markdown formatting issues. Otherwise, LGTM.

[rhuss]

Thanks @maximilien for the feedback, highly appreciated!

• plurals of names. So kn services create ... should be OK and same kn service create ... Like kubectl

This makes much sense imo and we should be more liberal here. Happy to open an issue for this

• putting verb before resource names. So I would also be in favor of kn create service ... to be same as kn service create ...

Here I'm not so sure, because of the hierarchy of command we are using. If we allow a verb as the first command, we might hit some issues:

• kn create help would need to show all creating commands for services, sources, triggers, ...
• For creating a source like the PingSource, would it be kn create source ping or kn create ping source ? or both ?
• What's about plugin which have a create in their somewhere in there name ? Are they considered to be shown in kn create help, too ? Should be "create" verbs on the second (aka service) or third (aka source) level be considered ?

I for myself often type kn create service as this is really one of the confusing aspects when using both kubectl and kn. But it was an early design decision to deliberately selected the "noun verb" format (this was before I joined Knative). Even when we decide we should allow this for a fixed set of verbs (describe, create, list, update, delete) this will get technically challenging (especially when dealing with plugins).

[mattmoor]

Produced via:
prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github | grep -v docs/cmd/)

[mattmoor]

Produced via:
prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github | grep -v docs/cmd/)

[mattmoor]

Produced via:
prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github | grep -v docs/cmd/)

[mattmoor]

Produced via:
prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github | grep -v docs/cmd/)

[mattmoor]

Format markdown:

Suggested change

	This document describes the conventions that are used for all `kn` commands and options.
	It is normative in the sense that any new feature that introduces or changes user-facing commands or options needs to adhere to the given principles.
	This document describes the conventions that are used for all `kn` commands and
	options. It is normative in the sense that any new feature that introduces or
	changes user-facing commands or options needs to adhere to the given principles.

[mattmoor]

Format markdown:

Suggested change

	Also, the given rules apply to plugins as well.
	Especially any plugin that wants to be promoted to the [knative/client-contrib](https://github.com/knative/client-contrib) plugin repository has to adhere to these rules.
	Also, the given rules apply to plugins as well. Especially any plugin that wants
	to be promoted to the
	[knative/client-contrib](https://github.com/knative/client-contrib) plugin
	repository has to adhere to these rules.

[mattmoor]

Format markdown:

Suggested change

	So, commands are generally of the form `kn <noun> <verb>` <sup>[1](#foot-1)</sup>, where [<noun>](#noun) is often the name of a resource (e.g. `service`) but can also refer to other concepts (e.g. `plugin` or `config`).
	This first noun forms a command group for all the operations you might want to do with that kind
	of resource.
	Sometimes there can be deeper hierarchies with multiple nouns (`kn <noun-1> <noun-2> .... <verb>`) when it makes sense to structure complex concepts.
	A good example is `kn source <source-type> <verb>` which is used like in `kn source ping create`.
	So, commands are generally of the form `kn <noun> <verb>`
	<sup>[1](#foot-1)</sup>, where [<noun>](#noun) is often the name of a resource
	(e.g. `service`) but can also refer to other concepts (e.g. `plugin` or
	`config`). This first noun forms a command group for all the operations you
	might want to do with that kind of resource. Sometimes there can be deeper
	hierarchies with multiple nouns (`kn <noun-1> <noun-2> .... <verb>`) when it
	makes sense to structure complex concepts. A good example is
	`kn source <source-type> <verb>` which is used like in `kn source ping create`.

[mattmoor]

Format markdown:

Suggested change

	`kn` commands take only positional arguments that are used as [identifiers](#identifier).
	This identifier is often the name of a resource which identifies the resource uniquely for the current or given namespace.
	`kn` commands take only positional arguments that are used as
	[identifiers](#identifier). This identifier is often the name of a resource
	which identifies the resource uniquely for the current or given namespace.

[mattmoor]

Format markdown:

Suggested change

	Top-level commands concerning the operation of `kn` itself, like `help` and `version` are also okay.
	Top-level commands concerning the operation of `kn` itself, like `help` and
	`version` are also okay.

[mattmoor]

Format markdown:

Suggested change

	Example:
	Example:

[mattmoor]

Format markdown:

Suggested change

```

[mattmoor]

Format markdown:

Suggested change

	Certain functionality is the same across command groups.
	For example, specifying resource requests and limits via flags can be done when managing services but also for sources.
	Those common functionalities should share the same conventions, syntax.
	Certain functionality is the same across command groups. For example, specifying
	resource requests and limits via flags can be done when managing services but
	also for sources. Those common functionalities should share the same
	conventions, syntax.

[mattmoor]

Format markdown:

Suggested change

	* Resource limits
	* Output formats, i.e. the data formats supported by the `--output` option (which is reused from k8s' _cli-runtime_)
	* Sinks
	* ....
	- Resource limits
	- Output formats, i.e. the data formats supported by the `--output` option
	(which is reused from k8s' _cli-runtime_)
	- Sinks
	- ....

[mattmoor]

Format markdown:

Suggested change

	<a name="foot-1">1</a>: Note that this differs from the `kubectl` model where this order is vice versa (`kubectl <verb> <noun>`)
	<a name="foot-1">1</a>: Note that this differs from the `kubectl` model where
	this order is vice versa (`kubectl <verb> <noun>`)

[navidshaikh]

/lgtm
/approve

[knative-prow-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: navidshaikh, rhuss

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [navidshaikh,rhuss]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment