Update content guidelines (#866)

README.md

@@ -8,7 +8,7 @@ If you are looking for information on how to join us, you are in the right place
 
 # <img src="assets/contribution-collaboration-icon.svg" width="120"> Contribution & Collaboration
 
-## Contribution rules
+## Contribution Rules
 
 Before you start contributing, read our [Code of Conduct](docs/contributing/01-code-of-conduct.md) and learn about our [working model](docs/governance/01-governance.md) to understand the way Kyma community works. Get familiar with the [contributing rules](docs/contributing/02-contributing.md), recommended [Git workflow](docs/contributing/03-git-workflow.md), and [issues workflow](docs/governance/03-issues-workflow.md) we use in Kyma so you can apply them later in practice as an active contributor.
 
@@ -26,7 +26,7 @@ The Kyma community collaborates through Special Interest Groups and Working Grou
 
 # <img src="assets/stay-informed-icon.svg" width="120"> Stay Informed
 
-## Social media
+## Social Media
 
 We're on Twitter (@kymaproject) and LinkedIn (Kyma Project). Stay tuned for the news and spread the good word about Kyma among your followers.
 

docs/README.md

@@ -1,5 +1,5 @@
 ---
-title: Get started
+title: Get Started
 ---
 
 Welcome to the Kyma community page!
@@ -8,7 +8,7 @@ If you are looking for information on how to join us, you are in the right place
 
 # <img src="assets/contribution-collaboration-icon.svg" width="120"> Contribution & Collaboration
 
-## Contribution rules
+## Contribution Rules
 
 Before you start contributing, read our [Code of Conduct](./contributing/01-code-of-conduct.md) and learn about our [working model](./governance/01-governance.md) to understand the way the Kyma community works. Get familiar with the [contributing rules](./contributing/02-contributing.md), recommended [Git workflow](./contributing/03-git-workflow.md), and [issues workflow](./governance/03-issues-workflow.md) we use in Kyma so you can apply them later in practice as an active contributor.
 
@@ -26,7 +26,7 @@ The Kyma community collaborates through Special Interest Groups and Working Grou
 
 # <img src="assets/stay-informed-icon.svg" width="120"> Stay Informed
 
-## Social media
+## Social Media
 
 We're on Twitter (@kymaproject) and LinkedIn (Kyma Project). Stay tuned for the news and spread the good word about Kyma among your followers.
 

docs/guidelines/content-guidelines/00-content-strategy.md

@@ -1,20 +1,18 @@
----
-title: Content Strategy
----
+# Content Strategy
 
-## Purpose and audience
+## Purpose and Audience
 
 This content strategy focuses on the publicly available documentation for the open-source [Kyma project](https://kyma-project.io). The source of the documentation displayed on the website is stored in [GitHub](https://github.com/kyma-project/kyma) and it's written in [Markdown](https://daringfireball.net/projects/markdown/).
 
 The assumed readers of this guide and contributors to the documentation have some basic knowledge of technical writing.
 
-## Information types
+## Information Types
 
 We follow a topic-based documentation approach, with one file per topic. Every documentation file has a clearly defined purpose, which is reflected in the title. The content must be able to stand on its own, but you link to other documents as needed.
 
 Here are the content types that we use in Kyma documentation:
 
-### Concept topics
+### Concept Topics
 
 Concept topics answer "what-is" questions and provide essential background information that users must know.
 You'll find most concept topics in the Overview section, but they can be useful elsewhere too.
@@ -23,7 +21,7 @@ Use nominal style for the title, for example, "Security" or "Security Concept".
 
 For all concept topics, use the [concept topic template](https://github.com/kyma-project/community/blob/main/templates/resources/concept.md).
 
-### Task topics
+### Task Topics
 
 Task topics provide "how-to" instructions that enable users to accomplish a task. Each task topic should tell how to perform a single, specific procedure.
 
@@ -34,17 +32,17 @@ It's good practice to have 5-9 steps; anything longer can probably be split.
 
 For all step instructions, use the [tutorial  template](https://github.com/kyma-project/community/blob/main/templates/resources/tutorial.md).
 
-### Reference topics
+### Reference Topics
 
 Reference topics are typically organized into one or more sections containing a list or table with data that is usually looked up rather than memorized.
 
 Reference topics provide quick access to fact-based information. In technical information, reference topics are used to list product specifications and parameters, provide essential data, and provide detailed information on subjects such as the commands in a programming language.
 
 Use nominal style for the title, for example, "Configuration Parameters".
 
-Use the templates for [architecture documents](https://github.com/kyma-project/community/blob/main/templates/resources/architecture.md), [configuration parameter charts](https://github.com/kyma-project/community/blob/main/templates/resources/configuration.md), and [Custom Resources](https://github.com/kyma-project/community/blob/main/templates/resources/custom-resource.md).
+Use the templates for [architecture documents](https://github.com/kyma-project/community/blob/main/templates/resources/architecture.md), [configuration parameter charts](https://github.com/kyma-project/community/blob/main/templates/resources/configuration.md), and [custom resources](https://github.com/kyma-project/community/blob/main/templates/resources/custom-resource.md).
 
-### Troubleshooting topics
+### Troubleshooting Topics
 
 Troubleshooting topics provide a condition that the reader may want to correct, followed by one or more descriptions of its cause and suggested remedies.
 
@@ -54,15 +52,15 @@ It's good practice to use three standard headlines (like “Condition”, “Cau
 
 For all troubleshooting topics, use the [troubleshooting topic template](https://github.com/kyma-project/community/blob/main/templates/resources/troubleshooting.md).
 
-### Release notes
+### Release Notes
 
 Release notes announce what's new in Kyma.
 
 After an introductory paragraph, a list briefly presents the new and changed features. Links lead to longer paragraphs that describe the changes in more detail.
 
 For release notes, use the [release notes template](https://github.com/kyma-project/community/blob/main/templates/resources/release-notes.md).
 
-## Target groups
+## Target Groups
 
 The general assumption is that the readers of the documentation is familiar with the following terms and does not need the explanation of technical concepts behind them:
 
@@ -71,19 +69,19 @@ The general assumption is that the readers of the documentation is familiar with
 
 These are the assumed target groups for Kyma documentation:
 
-### Decision maker
+### Decision Maker
 
 Assesses the software to make sure that it meets the company's needs. Requires the facts – not just marketing spin – before signing on the dotted line. Wants to choose the right solution for the company, and ensure stakeholders back this decision.
 
-### Software developer
+### Software Developer
 
 Interested in technical topics. Solid knowledge of programming languages. Experienced in programming and development projects. Expert in the technical or business area. Uses and contributes to community content. Wants to develop, maintain, and enhance software.
 
 ### Admin/Operator
 
 Deals with installation, upgrades, system troubleshooting. Wants to support the ongoing operations and evolution of the Kyma implementation.
 
-## Documentation structure
+## Documentation Structure
 
 On the Kyma website, we have five main tabs containing multiple documents each, plus a glossary.
 
@@ -105,13 +103,13 @@ Contains a guide/tutorial that covers typical steps you need to perform to get s
 
 Under this tab, there are subtabs according to main areas (except UI – user interfaces are mentioned as needed within the instructions of the respective main area). Documents in the subtabs contain "how-to" instructions that enable users to accomplish a task.
 
-### Operation guides
+### Operation Guides
 
 **Target Group**: Admins/Operators who make sure the Kyma cluster is configured as needed and keeps running in a healthy and secure way.
 
 Contains installation and configuration instructions, backup info, security documentation, and troubleshooting guides.
 
-### Technical references
+### Technical References
 
 **Target Group**: Users who want to look up specific detailed information.
 

docs/guidelines/content-guidelines/01-user-docs.md

@@ -1,4 +1,4 @@
-# User documentation
+# User Documentation
 
 Open-source Kyma and Kyma module user documentation is displayed at [`https://kyma-project.io`](https://kyma-project.io/#/). The website uses [docsify](https://docsify.js.org/#/) as a documentation site generator.
 
@@ -11,23 +11,21 @@ After initialization, to run, docsify uses the following files located in the `/
 - `.nojekyll` preventing GitHub Pages from ignoring files that begin with an underscore
 - `_sidebar.md` listing all Markdown documents to be displayed and ruling navigation between those documents on the website
 
-> **NOTE:** If you have a flat directory structure, with all Markdown files on the same level, you need only a single `_sidebar.md` file listing the Markdown documents to be displayed. However, if there are subfolders, you need one `_sidebar.md` per folder for the navigation between the documents to work properly.
-
-## Publish a document from the `/kyma` repository
+## Publish a Document from the `/kyma` Repository
 
 To publish a document located in the `/kyma` repository, follow these steps:
 
 1. Create a pull request adding your content to a Markdown file located in the `/docs` folder.
 2. Add a new `_sidebar.md` file including a link to your document, or update an existing `_sidebar.md` to include it.
 
-## Publish a document from an existing module repository
+## Publish a Document from an Existing Module Repository
 
 To publish a document located in an existing module repository, follow these steps.
 
 1. Create a pull request adding your content to a Markdown file located in the `/docs/user` folder in your module repository.
 2. In the `docs/user` folder, add a new `_sidebar.md` file including a link to your document, or update the existing `_sidebar.md` to include it.
 
-## Publish a document from a new module repository
+## Publish a Document from a New Module Repository
 
 To publish a document located in a new module repository, follow the steps from [Publish a document from an existing module](#publish-a-document-from-an-existing-module-repositiory). Once completed, do the following:
 

docs/guidelines/content-guidelines/02-style-and-terminology.md

@@ -1,6 +1,4 @@
----
-title: Style and terminology
----
+# Style and Terminology
 
 When writing Kyma documentation, refer to the following guidelines for grammar, capitalization, and preferred word choices. These guidelines help ensure that all contributors write in the same way to ensure a uniform flow throughout the whole Kyma documentation.
 
@@ -10,14 +8,14 @@ When writing Kyma documentation, refer to the following guidelines for grammar,
 
 These are the generally accepted grammar rules for writing Kyma documentation.
 
-### Active voice
+### Active Voice
 
 Use active voice whenever possible. Active voice is clear, concise, and it avoids misinterpretation. It is also easier for non-native speakers to understand. Passive voice is indirect, uses more words, and can be misleading because it reverses the logical order of events.
 
 ✅ The endpoint path includes your service name.  
 ⛔️ Your service name is to be included in the endpoint path.
 
-### Voice and tone
+### Voice and Tone
 
 There are different tones for different types of technical documentation, which can range from instructional to somewhat conversational. The goal is always to support people using the product and, in blogs and release notes, also to help business users understand changes.
 
@@ -91,18 +89,18 @@ Whenever you point to the outside sources, research whether the name of the sour
   ⛔️ kubernetes  
   ⛔️ k8s
 
-### Sentence case
+### Sentence Case
 
 Use [Sentence case](https://dictionary.cambridge.org/dictionary/english/sentence-case) for:
 - Standard sentences
-- Headings
-
-> **NOTE:** For more details about [headings](03-formatting.md#headings), see the Formatting guidelines.
 
 ### Title Case
 
 Use [Title Case](https://dictionary.cambridge.org/dictionary/english/title-case) for:
 - The names of Kyma components, such as Application Connector or API Gateway Controller
+- Headings
+
+> **NOTE:** For more details about [headings](03-formatting.md#headings), see the Formatting guidelines.
 
 ### CamelCase
 
@@ -137,7 +135,6 @@ See the following examples of Kubernetes resources:
 * Deployment
 * Function
 * Ingress
-* Namespace
 * Node
 * PodPreset
 * Pod
@@ -148,6 +145,8 @@ See the following examples of Kubernetes resources:
 * ServiceClass
 * ServiceInstance
 
+> **NOTE:** Do not capitalize the word "namespace".
+
 ## Terminology
 
 Use the American English spelling, not British English.

docs/guidelines/content-guidelines/03-formatting.md

@@ -1,14 +1,12 @@
----
-title: Formatting
----
+# Formatting
 
 Format the content in an attention-grabbing way. In general, content is easier to read when it is in chunks. Consider breaking up endless paragraphs by using a list or a table. Use action verbs and present tense for headings to engage the reader, and also follow the guidelines for the best way to include links and images. When you include lists, tables, code samples, or images, precede them with a brief explanation of what they describe.
 
-## Code font and bold font
+## Code Font and Bold Font
 
 It is important to consistently format items such as code or filenames to quickly distinguish them while reading technical documentation. The following tables outline when to use **bold** font and when to use `code` font:
 
-### Use bold font for these items:
+### Use Bold Font for These Items:
 
 Items       | Examples
 ----------- | ----------------------------------------------------------------------
@@ -19,7 +17,7 @@ Roles        | Only the users with the **kyma_admin** role can list Pods in the
 UI elements  | Click **Subscribe**.
 Variables and placeholders | Click **Project** > **{YOUR_PROJECT_NAME}**.
 
-### Use code font for these items:
+### Use Code Font for These Items:
 
 Items                     | Examples
 ------------------------- | -----------------------------------------------------------------------------------------------
@@ -42,7 +40,7 @@ Custom resources (if you want to refer to the code specifically) | Define the **
 > `To adjust the number of Pods in your Deployment, edit the [deployment](./deployment.yaml) file.`
 
 
-### Omission in code
+### Omission in Code
 
 Often when you quote snippets of code, it is not necessary to include them in full. For example, when you quote an HTTP response, it is enough to quote only the relevant part instead of enclosing the whole response. In such a case, replace the omitted parts with `...` to signalize that something has been removed.
 
@@ -88,7 +86,7 @@ See an example:
 
 >**NOTE:** Provision a Public IP for Ingress and a DNS record before you start the installation.
 
-## Ordered and unordered lists
+## Ordered and Unordered Lists
 
 As you write about your topic, use lists to create visual clarity within your content. List items in a category or in a sequence. Use an ordered list for sequential, instructional steps. Unordered lists are appropriate for items that have no sequential order, such as a list of valid file types. Follow these guidelines:
 
@@ -122,8 +120,8 @@ When creating a table, centralize the columns that have choice-type values, such
 ## Headings
 Ideally, headings fit into one line in the generated output. Be concise, but also make sure to adequately describe the main point of the document or a section. Follow these guidelines when writing headings:
 
-* Write headings in sentence case. For example, **Expose a service**.
-* Use action verbs and present tense verbs in headings when possible, especially in tutorials. For example, **Add a document type**.
-* While gerunds are acceptable in body-level content, DO NOT use gerunds in headings. Use **Create a storefront** instead of **Creating a storefront**.
+* Write headings in title case. For example, **Expose a Service**.
+* Use action verbs and present tense verbs in headings when possible, especially in tutorials. For example, **Add a Document Type**.
+* While gerunds are acceptable in body-level content, DO NOT use gerunds in headings. Use **Create a Storefront** instead of **Creating a Storefront**.
 * Avoid stacked headings, which are headings without body-level content in between. For example, DO NOT use a Heading 2 (H2) to introduce one or more Heading 3s. Instead, add a paragraph after the H2 that describes the main idea of the content in the headings that follow.
 * Do not use small headings, such as Heading 4 (H4) and smaller. Use Heading 1 (H1) for the document title, and Heading 2s (H2) and Heading 3s (H3) to organize the content of the document.

docs/guidelines/content-guidelines/04-ui-elements.md

@@ -1,6 +1,4 @@
----
-title: UI elements
----
+# UI Elements
 
 Contrary to the regular technical documentation, UI elements follow different guidelines and best practices. Due to the limited space you can use to convey a message, your UI text must be as precise and concise as possible. Use the following general guidelines to design and write content for UI elements:
 
@@ -109,7 +107,7 @@ There are many different types of messages appearing in every UI. The most commo
 - Use punctuation in case of messages that are full sentences. In case of clauses (fragments of a sentence), omit punctuation.
 - Use title case for the title of your pop-up message. Keep it as simple as possible and omit punctuation. For more information, see [Labels](#labels).
 
-### Error messages
+### Error Messages
 
 An error message informs about unsuccessful outcome of an action or conveys any other negative information, so you must choose your words wisely not to upset the user. Here are some tips that will help you design your error message:  
 
@@ -124,7 +122,7 @@ An error message informs about unsuccessful outcome of an action or conveys any
 - Avoid title case. It can give users a feeling they are being looking down on.
 
 
-## Placeholder texts
+## Placeholder Texts
 
 A placeholder is a tricky UI element. It tends to disappear when the user clicks a given form field, so it requires them to use their memory, which increases memory load and hurts usability. For this reason:
 
@@ -138,7 +136,7 @@ A placeholder is a tricky UI element. It tends to disappear when the user clicks
 
 Follow these resources for further reference:
 - [UI Text Guidelines for SAP Fiori Apps](https://experience.sap.com/internal/fiori-design-web/ui-text-guidelines-for-sap-fiori/)
-- [5 rules for choosing button labels](https://uxmovement.medium.com/5-rules-for-choosing-the-right-words-on-button-labels-dc3f74c2c2a3)
+- [5 Rules for Choosing the Right Words on Button Labels](https://uxmovement.medium.com/5-rules-for-choosing-the-right-words-on-button-labels-dc3f74c2c2a3)
 - [Tooltip Guidelines](https://www.nngroup.com/articles/tooltip-guidelines/)
 - [Tooltips: How to Craft Effective Guiding Text](https://www.wix.com/wordsmatter/blog/2020/06/tooltips/)
 - [Placeholders in Form Fields Are Harmful](https://www.nngroup.com/articles/form-design-placeholders/)