Client documentation rehaul

[rhuss]

Describe the feature:

I would like to start a discussion around our documentation as I think it is currently in a not so good state, and I think we could expand on the documentation at various angles.

• The README is not much more than a skeleton and has the wrong focus (why makes setting up bash-completion half of the document ?). I suggest completing rewrite it and add at least:

  • Top-level goal and features
  • Simple 1 min usage example (maybe even with asciicinema)
  • Links to
    • Tutorial
    • Reference Manual with a chapter per commmand
    • External links (WG docs, WG call link, CI link, Slack, Mailing list)
    • Use case driven description (e.g. how to make a canary release)
    • FAQ
    • Tipps & Tricks a la knative.tips (maybe the folks behind knative.tips could contribute to our documentation ?)

• README: Update README.md #437

• A reference manual which is more than the auto-generated pieces. It should be clearly structured, having quick navigation to a kn command (like having all top-level commands in left-side column something like in https://maven.fabric8.io/). However not sure where this should be hosted, probably integrated with knative.dev (with the source for docs hosted where ?). The reference manual should also include section for important concepts like plugins etc.

• Add frontmatter to auto generated documentation to be picked up knative.dev Add Hugo frontmatter to generated docs #539

• A user manual with use-case oriented documentation.

  • How to create a simple service ?
  • What can be configured for the service ?
  • How to implement various update strategies with traffic splitting ?
  • How to write a plugin ?
  • How to use bash completion ?
    ....

• This should be part of knative.dev (to minimize duplication efforts) --> #650

• FAQ and tips like in knative.tips

• Part of Knative.dev --> #651

• Developer Handbook

• --> Add a Developer Handbook #652

• Collection of mini-screencasts (?)

...

For each of these items, I'd like to create different tracking issues.

Wdyt ?

[abrennan89]

Hi @rhuss 🙂 thanks for creating this issue and for providing a detailed outline.
I would say that the screencasts are out of scope for the docs team (and also maybe READMEs if these are in dev repos?), and also that rather than hosting CLI somewhere else it should definitely be integrated with knative.dev's new nav proposal, but otherwise this looks good.

@RichieEscarez do the docs WG generally work on READMEs? Does this scope look reasonable to you?

[rhuss]

No worries about the initial README. I would take care of the README (as its more about a landing page referencing the 'real' documentation and possibly some deep links).

[RichieEscarez]

This all sounds great @rhuss. We are also thinking about all this and have put together a Navigation restructure proposal and have opened several high-level (issues) in this project.

[RichieEscarez]

Note the discussion about this work in the Knative Docs Working Group

[sixolet]

I would very much love to have the reference docs integrated with knative.dev, and have a good way to generate things into the reference docs as "overview" pages, that aren't for specific commands.

[samodell]

+1! That is definitely on our radar. We're going to have a meeting (@abrennan89 , @rhuss , and @RichieEscarez ) about getting started with these docs; would you like to be on that meeting, @sixolet ?

[abrennan89]

/project Kn Client Docs

[knative-prow-robot]

@abrennan89: You must be a member of the knative/client github team to set the project and column.

Details

In response to this:

/project Kn Client Docs

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.