End User Documentation Story

[ahawkins]

I'm opening this issue after discussion with @kris-nova. Hopefully it can start a thread discussion between maintainers and users on documentation story. I'm sharing my experience as a team lead, #kops channel member, and general end user.

My team and I are working with kops every day. I understand it's a very active project and things are changing rapidly. This requires end users (such as myself) to be more participatory in the community because the only real knowledge exists in people's heads. This is natural at this stage in a project but it doesn't scale. Better high level documentation and discoverability would improve the situation.

Discoverability is hard. I don't look at source code for documentation on how to use a tool. I look on project webpages. I know I can find docs in the source, but I don't expect them to be organized nor tell a story. High level documentation is lacking as well--especially if you are beginner. Provisioning k8s is no small task. kops is "the way" to deploy clusters on AWS (and GCP outside of GKE). It's a turn key solution. This attracts many people like myself who are experienced infrastructure engineers but are not at the same level with k8s. We "just want a cluster" without having to fine tune everything. I see the same type of questions asked in the slack channel as well. I know this situation can improve with better and more useful documentation (especially aimed at new years). Here are few suggestions for the maintainers:

1. Move docs out of source and onto a project page (github pages perhaps)
2. Organize docs to tell a story (e.g. how to provision a new cluster, what tradeoffs to consider, what kops can and cannot do)
3. Create a bootstrap guides for:
   • provisioning a new cluster into a greenfield.
   • provisioning a new cluster inside an existing network. Specifically what features are not available in this scenarios or other things to consider with kops
4. Provide terse reasons for the various --topology, --dns, --network-manager, and friends setting. It's not kops job to say everything but a few sentences would drastically improve the UX for people new to kops and/or k8s.
5. What kops cannot do. It's sucks to spend says working with a tool to find out that it does not support your use case (especially those deploying to existing infrastructure).
6. how to share kubectl config with others (I know about kops export but I couldn't find it in an obvious way).

I think orienting the documentation around creating clusters is the best way to help users. It's my guess the majority of people are coming to kops for this specifically, so targeting it provides the most ROI.

Thank you all for this. I hope this provides insight <3

---

Related issues:

• kops create -f examples #1735
• kops 1.6 themes #1649
• document necessary iam permissions #223

[blakebarnett]

Personally I love having the docs in the git repository, I'd prefer something that synchronizes the docs to a github site (like kubernetes.io today). 👍 on everything else!

[ahawkins]

I'd prefer something that synchronizes the docs to a github site (like kubernetes.io today).

Ya that makes sense. Having docs under SCM is a great. Just need to make them more discoverable for those who are not purely looking for source code.

[apenney]

I agree with all the above points! We really have two different sets of documentation living together right now, there's the "reference" material, the canonical "show me all networking options" documents and then "guides", show me how to satisfy individual use cases.

I think we need to actively detangle these into two separate concepts, and be clear about which documents are which.

[yissachar]

Agreed with @apenney.

The main Kubernetes docs site does a good job splitting docs into the following categories:

• Guides
• Tutorials
• Tasks
• Concepts
• Reference
• Tools
• Samples

There's some overlap between guides, tasks, and tutorials, and I don't think we need tools or samples. So for kops I think we could simplify things a bit to:

• Guides (e.g. setting up a cluster, setting up a cluster with shared VPC/subnet, etc.)
• Concepts (e.g. explain topologies)
• Reference (raw CLI options, spec format, etc.)

[krisnova]

Another related issue on versioning the documentation with each release #1583

[chrislovecnm]

@kris-nova I am kinda torn of versioning documentation. We need to push docs to kubernetes.io with each release, and if we get into a regular cadence with releases we should have tags for each versioned documentation. Aren't we already versioning it?

@yissachar we have been given permission to create our own section on the kubernetes.io site, It would be awesome to have the same type of layout inside the site itself. Thoughts?

@ahawkins you kinda wrote an epic, you mind breaking it apart into smaller epics or stories?

cc: @scottmwebber can you pipe in?

[ahawkins]

@chrislovecnm Here's a breakdown:

• Guides Publish user guides on a project website (kuberenets.io or anything other than source code)
  • Installing and configuring kops (e.g. configuring the state store and all that)
  • Deploying a new cluster to new infrastructure. See outline below:
    • Configuring DNS
    • Deciding a topology
    • Deciding on DNS (public vs private)
    • Adding a bastion
    • Sharing access to the cluster
    • Making changes to the cluster
    • Adding multi-masters
    • What to do next?
  • Deploying a cluster to exiting infrastructure. See outline below
    • Pre-requites: deciding what topologies and other things are supported for your deployment scenarios
    • Which information to pass to kops
• Concepts Document all infrastructural difference between topologies and their implementation details
• Move video and other short docs out of readme and point to documentation site

That's a rough roadmap off the top of my head. I'm using this model:

• Guides (e.g. setting up a cluster, setting up a cluster with shared VPC/subnet, etc.)
• Concepts (e.g. explain topologies)
• Reference (raw CLI options, spec format, etc.)

Guides and concepts need the most improvement. Guides are the most important. I find the CLI options are documented, but not enough information on how they're implemented and used (concepts).

I hope this helps.

[krisnova]

Thanks @ahawkins this is great!

Friendly reminder that we will be going over this on the office hours call tomorrow.

CC @evildandelions

[scottmwebber]

Chris: Adam's email is an excellent starting point. I would suggest that the bigger picture be added: 1. Roadmap 2. Value Hierarchy - What business outcomes will come from using KOPS - Recommend using the Kano model (below). This should be concise and easy to call consume. [image: Inline image 1] Otherwise, I'd say let's pound out Adam's list. Scott

…

On Thu, Feb 2, 2017 at 10:41 AM, Adam Hawkins ***@***.***> wrote: @chrislovecnm <https://github.com/chrislovecnm> Here's a breakdown: - *Guides* Publish user guides on a project website (kuberenets.io or anything other than source code) - Installing and configuring kops (e.g. configuring the state store and all that) - Deploying a new cluster to new infrastructure. See outline below: - Configuring DNS - Deciding a topology - Deciding on DNS (public vs private) - Adding a bastion - Sharing access to the cluster - Making changes to the cluster - Adding multi-masters - What to do next? - Deploying a cluster to exiting infrastructure. See outline below - Pre-requites: deciding what topologies and other things are supported for your deployment scenarios - Which information to pass to kops - *Concepts* Document all infrastructural difference between topologies and their implementation details - Move video and other short docs out of readme and point to documentation site That's a rough roadmap off the top of my head. I'm using this model: - Guides (e.g. setting up a cluster, setting up a cluster with shared VPC/subnet, etc.) - Concepts (e.g. explain topologies) - Reference (raw CLI options, spec format, etc.) Guides and concepts need the most improvement. Guides are the most important. I find the CLI options are documented, but not enough information on how they're implemented and used (concepts). I hope this helps. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1754 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AXKHM-srBJA6eswBLbFpj_UBjBkFzsmMks5rYiNAgaJpZM4L0LKI> .

-- Scott M. Webber 925-482-4492 (cell)

[ahawkins]

@scottmwebber can you add your image again? It didn't get connected via email. I'm curious about the KANO model--I've not heard of it :)

[chrislovecnm]

Guides Publish user guides on a project website (kuberenets.io or anything other than source code)

I have been instructed by the community manager @sarahnovotny, to get the docs there :) They do not have an option for kops to have its own website, and since we are under the umbrella of CNCF, that is what this community needs to doc.

We need to get tooling in place to copy documentation from this repo into a PR into the website or move all of our docs to the website. We will need to get tooling in place for at least the cobra generated cli docs.

find the CLI options are documented, but not enough information on how they're implemented and used

There are issues filed to improve the CLI cobra documentation template layout and appropriate the code from kubectl for those templates.

@ahawkins we are also missing API documentation on this list. We already have API that needs some TLC, but still and API. Talking with @scottmwebber tonight we went over some ideas for a value prop and the roadmap that has been discussed with the core developers before.

All exciting stuff ... Actionable results :) Really appreciate the time and thought you took with this @ahawkins!

[ahawkins]

🎉 Having user guides / docs on the official Kubernetes website will help all users and bolster user confidence in kops. It makes it easy to see that kops is part of the official toolchain.

All exciting stuff ... Actionable results :) Really appreciate the time and thought you took with this

@chrislovecnm 🙇 You & the other maintainers are doing all the hard work. I'm just opening issues :)

[chrislovecnm]

Adding a related issue - #1194

@scottmwebber is adding a google doc, for onboarding new developers. We will drop it into a markdown document, but it is more efficient for @scottmwebber to work in google docs up front.

[chrislovecnm]

@ahawkins / @scottmwebber just created kubernetes/website#2463 to get the ball rolling on adding our docs to k8s website.

[chrislovecnm]

@ahawkins we always appreciate new contributors ... wink wink ... nudge nudge

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle rotten
/remove-lifecycle stale

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close