Add User Manual

[rhuss]

Describe the feature:

The user manual should be use case focussed and guide the user through several important use cases. That's different to the reference manual which is more for a quick lookup of options.

The user manual should live on knative.dev, we just track the issue here (but could move it over, too)

I could imagine a TOC like in:

• Installation of kn: https://knative.dev/docs/install/client/install-kn/

• Authentication and configuration: config is here https://knative.dev/docs/install/client/configure-kn/, not sure what is meant by authentication in this case

• Knative Serving

  • Create a simple service and verify that its running: creating a service using kn is documented; https://knative.dev/docs/serving/services/creating-services/#procedure we maybe need a follow up issue to improve the creating services docs in general, inc. verification steps etc, but I think that's outside the scope of just kn docs
  • Document use of kn service create --force #5227
  • What is a BYO revision name and why it is useful ?
  • How to tune concurrency parameter ?
  • How to change requests/limits
  • How to add labels
  • How to update a service ?
  • What is a Traffic split ?
  • How can I perform a canary deployment ? A blue green deployment ?
  • How can I rollback ?
  • What does the output of kn service describe actually means, especially the output for the traffic split ?
  • What the difference between latest created and latest ready and how can I see this in the client ?

• Knative Eventing

  • [EPIC] Basic examples for event sources #5056
  • Which sources are supported ?
  • How to use triggers and what are the prerequisites ? (i.e. a broker that is enabled)
  • Which sink types are supported ?

• Plugins

  • What is a plugin and how can I implement it ?
  • Where to find plugins ? (client-contrib)
  • How to install a plugin and how does the lookup mechanism work ? How can this be changed/configured ?
  • How to list all plugins ?
  • How does a eventing source plugin looks like and how it is different to other plugins ? (i.e using a manifest)

The style of the user manual should be relaxed and easy to read. The section can build upon each other.

The User Manual is hosted as part of knative.dev

This issue is part of knative/client#510

[daisy-ycguo]

I hope to help with the eventing part. Please let me know how to start.

[daisy-ycguo]

/assign

[rhuss]

Sounds good ! I have a crazy busy week ahead, but if you have any ideas how you would like to structure the eventing docs, let me know. We can already start with sandbox/docs in client-contrib (or we might open a client-sandbox repo for this ?)

[abrennan89]

@rhuss should this be filed against the /docs repo instead? 🤔

[rhuss]

@abrennan89 I think that makes totally sense. Is there already an issue related to where to integrate client documentation ?

[abrennan89]

There's a project for kn docs: https://github.com/knative/docs/projects/23
I've just been adding related issues there as I find them.

[rhuss]

@abrennan I'd like to move this issue also over to the docs repo, and also want to split it up more. This issue would be a candidate to discuss in one of the next calls.

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen.Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[rhuss]

/remove-lifecycle stale

[abrennan89]

Note to self: Related to knative/ux#39

[abrennan89]

@daisy-ycguo @rhuss is anyone currently working on this or should we unassign it and split up the issue into smaller tasks?

[rhuss]

@abrennan89 no, nobody is actually working on this issue (an @daisy-ycguo is not working on Knative anymore ...)

[abrennan89]

I don't think that this should be one single guide for CLI, but let's see what comes out of Omer's card sorts in terms of docs structure.
I think this should've been filed as individual issues per topic, not one giant issue, but I've converted the list to checkboxes. I think in the meantime let's cross off what already exists in docs and fill any gaps, then the kn content in the site can be restructured later if it needs to be.

[abrennan89]

@snneji any thoughts on where this fits into the new card sort version of docs? I don't think we have a CLI section anymore but kn is a major part of Knative.

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[rhuss]

/remove-lifecycle stale

[abrennan89]

@psschwei it looked like you were working on some sort of automation for this, is that still the plan going forward? Not sure if there's any work to do here still?

[psschwei]

I just added a link to the client docs to the knative docs... it would be good to add it to the site (rather than linking out), but it's not something I'd be able to work on in the near future...

[abrennan89]

Proposal for docs WG - how do we feel about adding top level CLI and Functions sections to the site, the same way we have for Serving and Eventing? More specifically, any arguments against doing this? To me they're the other two largest UX components that I could see folks wanting to find quickly. cc @psschwei @csantanapr @snneji

[abrennan89]

cc @nainaz

[abrennan89]

We have discussed this one in the Docs WG and although we have decided not to include the content in this exact format / layout, we plan to check that each of these requests are documented, or else maybe open individual issues for dealing with any gaps in the docs.

[abrennan89]

What does kn service create --force ?

What would the user story be for this @knative/client-wg-leads ? Does it really need to be documented? Why?

[abrennan89]

Plugins requirements split into separate issue: #3534

[rhuss]

@abrennan89 knative service create --force is to entirely overwrite an existing service, which means delete it first and then recreate it. This is in contrast to kn service update, which updates individual fields on an existing installation. You would use it in scripts to ensure that you have a fresh service even if a service with this name already exists. That's useful e.g. for CI runs when you are not sure that the previous run has been cleaned up properly (which can happen when a CI tests fails).

Also it's different to kn service apply as it does not merge on an existing service, that might have been changed by a third party. It just overwrites any changes that had happened. It's a sledgehammer.

[abrennan89]

Closing this since the issue has been open for over 2 years. @rhuss please do not open XXL issues like this, and instead open an issue for each individual section if there are changes still required. Opening issues that are this large make working them unmanageable.

[rhuss]

I'm fine with closing this issue. @abrennan89 this issue was never meant as a task list for things to perform, but as brainstorming and an example of how a user document could contain. It should not have been taken literally, but have some arguments why a use case focussed User Manual might have been helpful in addition to the Reference Manual we have.

I could imagine a TOC like in: ....

"could imagine" was the important part, which was meant to continue the discussion that has been started in knative/client#510

But I agree that a GitHub issue may be the wrong format for this, possibly a Google Docs would have been better. I also apologize that I could not drive that story more (e.g. splitting it up was one of the following goals).