Documentation Style Guide and Word List

[StackScribe]

Goal

A style guide promotes consistency across a documentation set that is developed by many people located around the world. It is also a useful aid for people who are writing the content.

Problem

• Adapt an existing, publicly-available style guide that is appropriate for open source projects and adapt this for Keptn projects. This gives us a comprehensive style guide that is appropriate for open source projects without requiring that we invest the significant resources required to implement such a guide for ourselves.
• Agree on level of compliance to use for this style guide (guideline only, enforce _in toto , or select elements to enforce
• Create a supplementary Keptn word list to supplement the word list in the adapted style guide.

Technical Details

I propose that we adapt the Google developer documentation style guide for the Keptn LTS, Keptn Lifecycle Toolkit, and Openfeature documentation.
The Kubernetes documentation style guide is much less comprehensive but may include specific elements that we want to adopt.

The Google style guide includes a word list that contains information about general usage, computer terms, and terms for Google products and features. We need to create word lists for our products to supplement this. Kubernetes does not provide a word list although they do provide a Glossary, although that omits many common Kubernetes words that should be defined and standardized.

This epic proposes the following process:

• Community brainstorms the word list asynchronously, using the Keptn/KLT word list Google doc. Anyone can suggest any of the following:
  • Terms whose spelling, capitalization, and/or usage needs clarification
  • Recommendations about appropriate spelling, capitalization, or usage of a term
  • Recommendations about terms, capitalization, and usage that is not acceptable
• Community decides whether to adopt the Google developer documentation style guide and the level of compliance to enforce (use as a guideline, enforce all elements, select elements to enforce). Decision to be included in the CONTRIBUTING.md file for any affected documentation set, with reference links for access.
• Community agrees on the location and format/conventions of the "official Keptn wordlist"
• As we get significant content in the brainstorming doc for the word list, we will spend some time at each Community meeting discussing some terms and come to an agreement. Meg will start to populate the "official Keptn wordlist" document incrementally with decisions reached at each meeting. This document will be published as a work-in-progress document as it is developed.
• When the Community agrees that the "official Keptn word list" has adequate content, publish this document officially. Additions and modifications will henceforth be proposed and accepted using standard modification procedures.

DoD

<when can we consider this piece of work completed?>

Tasks

Preview Give feedback

1. Create gdoc for brainstorming word list #813
   stale +1
2. Define how we handle apiVersion info in reference pages #1285
   documentation stale +2
3. Clarify KeptnTaskDefinition and KeptnTask #387
   documentation +1

~
"epic-template" 22L, 306B
🧇