Policies and practices for new tutorials

[StackScribe]

The existing tutorials are mostly outdated and are being retired (https://github.com/orgs/keptn/projects/16 ). We need to establish policies and practices for tutorials going forward. This issue is to discuss.

• Create tutorials only for important subjects that are handled best by a tutorial. Tutorials are the most resource-intensive content to create and maintain.
  • If one just needs to describe a procedure such as installation, a written list of steps that can address different environments and such. Videos can supplement the prose listing the steps.
  • In addition to tutorials like Quick Start (appropriate for the keptn-curious and new users), tutorials are appropriate for complicated advanced topics where the hands-on experience is useful, such as sophisticated manipulation of SLIs and SLOs.
• We recommend using Killercoda for most new tutorials so the user can concentrate on the specific exercises without getting bogged down with installation.
• Tutorials should include appropriate references to the documentation, especially reference pages
• All new tutorials should be coded in markdown with source code stored in a Github repo under Keptn
• All new tutorials must have an owner who will maintain the material.
• Need to define a standard location for published tutorials, preferably as part of the documentation site, and either located in or referenced from appropriate documentation sections

[vadasambar]

Tutorials are appropriate for more advanced topics, such as sophisticated manipulation of SLIs and SLOs.

Seems like quickstart might not fit under the definition of tutorial. Do we have any specific topics we intend to cover as a part of tutorials?

[StackScribe]

@vadasambar Goodness, I was careless in my prose above. I just reworded it. Is the new text less disturbing?

Yes, I do consider the Quick Start to be a tutorial -- just meant to say that tutorials for complex advanced topics are also appropriate. I'm not convinced that we need a bunch of tutorials for the keptn-curious like we had before, like a different one for each observability platform. It seems to me that the Quick Start is high-level and that the user can get the idea of how quality gates works by using any observability platform, not necessarily the one they will actually use.

Of course, if anyone wants to sign on to develop and maintain tutorials for different observability platforms. The Killercoda exercise (which will be named Quick Start for the LTS release) is structured so that one could easily replace just the one module to use Datadog or Dynatrace. If one creates a complete tutorial for another observability platform, one must then do maintenance on the whole things. A better approach might be to keep the single tutorial but, when it's time to do quality gates, have the tutorial fork with a message like "For our next exercise, you can choose whether to use Promtheus, Datadog, ..." and let them click on their choice. At the end of that section, everyone would come back to the common material.

If you are interested in that, you could talk to @afzal442 for help and guidance.

[DavidPHirsch]

close as not planned