[WIP] Define documentation style issues

[StackScribe]

Description

We lack standards for some key style issues in the documentation. While these issues are less critical than good content and structure of the docs, consistency gives the docs a more professional look. General proposal is to accept the recommendations in the Google developer documentation style guide, which is comprehensive and reasonable.

Issues

• Capitalization for titles. Recommend using sentence case. (See Google Capitalization in titles and headings
• American vs. British spelling. We currently have a mix and the Spell checker accepts both. Recommend requiring American spelling. (See Google Spelling and [Wikipedia: Manual of Style/Spelling) )
• Sentence structure when telling the reader to do something. Recommend defining what to do before the instructions. (See Google Sentence structure
• Use of "please" in instructions. Recommend not using "please". (See Google Politeness and use of please)
• Should we recommend timeless documentation that avoids words and phrases that anchor the docs in time? Recommend yes. See Google Timeless documentation
• Kubernetes terms
  • https://main.lifecycle.keptn.sh/contribute/docs/word-list/#kubernetes-terminology
  • Secret or secret
• Do we agree to use the Google developer documentation style guide in general? The Contributing Guide currently has this recommendation but we should officially agree to it as a community.
• New doc tools cannot handle hyphens in headers. This means we cannot use strings like "pre- or post-deployment" or "pre-defined" in headers. This does not preclude using the hyphenated terms in text but recommend favoring consistency so need to use "pre/post deployment" and "predefined"

DoD

Mostly updates to Contributing Guide, which should be brief with lines to the appropriate Google page:

• Contributing Guide defines practice for capitalization in titles
• Contributing Guide defines practice for American and British spelling
• Word list has table of Kubernetes terms showing capitalization
• Spell checker modified to exclude British spellings
• Contributing Guide defines use of "please" in instructions
• Contributing Guide discusses timeless documentation

[aryasoni98]

I would like to work on it @StackScribe . Can you assign me this issue .

[mowies]

We are gonna refine this ticket on wednesday in the Keptn community meeting. Afterwards, I'll gladly assign the issue to you :)