What should be the purpose and format of the guides?

[daxelrod-datto]

Before we work on updating the guides in https://github.com/openshift-cs/okd.io/blob/main/docs/guides/overview.md , let's come to a consensus on what their purpose is and what form we want them to take. We already have product documentation on the installation process, and we don't want to copy-paste that, so what's the value here instead?

My proposal

Here's what I'd like to propose to get the conversation started. This tries to describe many of the existing guides. Please suggest something else if you like!

Purpose

The installation product documentation must be comprehensive, leading the user through many possible decisions and options for them to customize their configuration. This can make it overwhelming for someone new to OKD.

Our guides, on the other hand, should be examples or case studies, showing the specific steps that someone took to install OKD in a particular environment having made one set of decisions.

This covers the following use cases:

• A user who is new to OKD and has not yet chosen an install target or method can look at Guides to see what the relative complexity of different types of installs will be
• A user who already has a particular environment that they wish to install OKD into can do a "trial run" by following a guide to get familiar with the process, so that when they tear it down and follow the product documentation, they have more context for the decisions they're making
• A guide author who's solved a neat problem installing OKD into a common or exotic enviornment can show off their work
• An OKD developer can see common patterns of the problems people have had to solve when installing OKD in order to inform the design of the installation process

Structure

Here is a proposed structure for guides to follow:

• Introduction
  • What problem was the author solving in this guide?
• Prerequisites (whichever apply)
  • Details of what hardware resources were used
  • Supporting infrastructure/platform
  • Pre-configuration steps
• Installation
  • Step-by-step
• Upgrades (optional)
  • On some UPI setups, upgrades are not completely automated. If this is the case for this guide, how does the author upgrade OKD?
• Results (optional)
  • Show off the resulting cluster and samples of what the author does with it

[daxelrod-datto]

@binnes @JaimeMagiera @sandrobonazzola @LorbusChris as people who have volunteered to work on doc updates, I'd love your input here. Thank you!

[LorbusChris]

+1 I like this a lot! Especially having a common structure for guides makes a lot of sense to me.

[brianinnes]

This looks good. We probably need to look at the existing guides on the site and see what changes are needed to bring them inline with the proposed template : https://www.okd.io/guides/overview/