Improve existing docs (#45)

* Update CONTRIBUTING.md

- Fix typos
- Consistent formatting
- Adding some Dos and Don'ts

* Improve existing docs

* Run prettier

* Fix lint command

* Add vale + one sentence per line

* More 1 line per sentence

* Remove vale errors

* Fix errors

* Adjust vale in pipeline

* Fix workflow

* Simplify workflow

* Improve grammar as found by textlint

* Fix spelling errors

* Change SDK pitch + fix grammar errors

* Improve tagline

* Fix overview/overview using grammarly

* Further improve overview/overview

* Improve benefits

* Fix formatting

* Improve using grammarly

* More improvements

* Improve docs

* Improve docs

* Lowercase app

* Improve docs

* Improve docs

* Remove comma dangle

@marikaner

* Apply suggestions from code review

Co-authored-by: Marika Marszalkowski <marika.marszalkowski@sap.com>

* Improve docs

* Improve docs

* Added context to CI step name

* Improve style rules

* Improve docs

* Improve docs

* Improve docs

* Improve style rules

* Add info comment to vale config

* Add info on linters in CONTRIBUTING.md

* Adjust PR template

* Fix compilation

* Set sidebar label and titles in title case

* Improve getting started guidelines

* Improve titles

* Add PR feedback

* Adjust warning levels

* Improve docs

* Improve docs

* Improve docs

* Proper SAP product naming

* Add rule for one line per sentence

* Remove outdated comments

* Improve docs

Co-authored-by: Marika Marszalkowski <marika.marszalkowski@sap.com>

.eslintrc.js

@@ -3,10 +3,7 @@ module.exports = {
     browser: true,
     es6: true
   },
-  extends: [
-    'plugin:react/recommended',
-    'standard'
-  ],
+  extends: ['plugin:react/recommended', 'prettier'],
   settings: {
     react: {
       version: 'detect'
@@ -23,8 +20,8 @@ module.exports = {
     ecmaVersion: 11,
     sourceType: 'module'
   },
-  plugins: [
-    'react'
-  ]
-//  ignorePatterns: ['static/**']
-}
+  plugins: ['react', 'prettier'],
+  rules: {
+    'react/prop-types': 'off'
+  }
+};

.github/ISSUE_TEMPLATE/sap-cloud-sdk-for-java-issue.md

@@ -4,7 +4,6 @@ about: Report issues with the SAP Cloud SDK for Java
 title: ''
 labels: Java
 assignees: ''
-
 ---
 
 <!--
@@ -13,33 +12,35 @@ Thank you for reporting an issue with the SAP Cloud SDK for Java. We prepared th
 Before you begin make sure you have checked out our list of [Frequently Debugged Problems](https://sap.github.io/cloud-sdk/docs/java/sdk-java-troubleshooting-frequent-problems) as well as having searched our tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sap-cloud-sdk).
 
 _Please_ take the time to fill out the information in this template. In _almost all cases it is vital_ to get a quick understanding of the problem and find out what is going wrong. It really enables us to come back to you with meaningful help as fast as possible.
- 
+
 Be sure to remove **any confidential** information (examples: credentials or internal URLs) before publishing the issue on the internet.
 -->
 
 ## Issue Description
+
 <!--
 Please provide a detailed description of your issue here. Use the points below as a guideline on what information might help us in answering your questions.
 -->
 
 Important information:
-- Your code 
+
+- Your code
 - Expected outcome
 - Actual outcome
 - Steps attempted to resolve the issue
 - In case of issues with any of our VDMs:
-    - What happens when a request is performed directly via an HTTP client tool such as Postman?
-    - In case that succeeds please provide details on the request such as URL, query parameters, header parameters, prerequisite requests (e.g. CSRF token), etc.  
+  - What happens when a request is performed directly via an HTTP client tool such as Postman?
+  - In case that succeeds please provide details on the request such as URL, query parameters, header parameters, prerequisite requests (e.g. CSRF token), etc.
 - Potentially missing information (open questions you might have)
 
 ### Impact / Priority
 
 <!--
  Please briefly state how this issue impacts your project and what your timeline is.
  -->
- 
+
 Affected development phase: e.g. Getting Started, Development, Release, Production
- 
+
 Impact: e.g. No Impact, Inconvenience, Impaired, Blocked
 
 Timeline: e.g. Go-Live is in 12 weeks.
@@ -55,7 +56,7 @@ Please make sure you [set your log level to debug](https://sap.github.io/cloud-s
 -->
 
 <!-- Maven Dependency Tree
-Please attach the Maven dependency tree of your project. You can obtain that by running "mvn dependency:tree" on the command line. Kindly note that you could have several pom.xml files in your project. If so, please provide the dependency tree for the pom.xml of the root module and the module named `application´ or `srv` that contains the application logic.
+Please attach the Maven dependency tree of your project. You can obtain that by running `mvn dependency:tree` on the command line. Kindly note that you could have several pom.xml files in your project. If so, please provide the dependency tree for the pom.xml of the root module and the module named `application` or `srv` that contains the application logic.
 -->
 
 ## Project Details
@@ -65,19 +66,19 @@ Please provide as much information about your project as possible.
 If you cannot share your project for confidentiality reasons, please consider providing a minimal working example https://en.wikipedia.org/w/index.php?title=Minimal_working_example&oldid=893866607
 -->
 
-* SDK Version: <your SAP Cloud SDK version here>
+- SDK Version: <your SAP Cloud SDK version here>
 <!-- The group id of the modules of the SAP Cloud SDK start with "com.sap.cloud.sdk" -->
-* Link to GitHub repo: <your link here>
-* Project type, for example:
-    * [ ] CAP Project
-    * [ ] SDK Maven Archetype
-    * [ ] None of the above:
-* Platform:
-    * [ ] Cloud Foundry
-    * [ ] Neo
-    * [ ] None of the above:
-
------
+- Link to GitHub repository: <your link here>
+- Project type, for example:
+  - [ ] CAP Project
+  - [ ] SDK Maven Archetype
+  - [ ] None of the above:
+- Platform:
+  - [ ] Cloud Foundry
+  - [ ] Neo
+  - [ ] None of the above:
+
+---
 
 ### Checklist
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,11 @@
-<!-- Make sure your change works as expected by running the documentation locally. -->
+## What Has Changed?
 
-Please provide a description of what your change does and why it is needed.
+Explain what you have changed.
+
+## Manual Checks?
+
+- [ ] Text adheres to the style guide (`vale docs/`)
+- [ ] Grammar has been checked (see `CONTRIBUTING.md`)
+- [ ] Every sentence is on it's own line
+- [ ] Files are consistently formatted (`npm run prettier`)
+- [ ] Documentation builds successfully (`npm run build`)

.github/workflows/build_documentation.yml

@@ -6,12 +6,18 @@ on:
 
 jobs:
   build:
-   runs-on: ubuntu-latest
-   steps:
-     - uses: actions/checkout@v1
-     - uses: actions/setup-node@v1
-       with:
-         node-version: '12.x'
-         run: |
-          npm ci
-          npm run build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v1
+        with:
+          node-version: '12.x'
+          run: |
+            npm ci
+            npm run build
+      - name: Vale (Linter for prose)
+        uses: errata-ai/vale-action@v1.3.0
+        with:
+          files: docs
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.nvmrc

@@ -0,0 +1 @@
+node

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json.schemastore.org/prettierrc",
+  "singleQuote": true,
+  "arrowParens": "avoid",
+  "trailingComma": "none"
+}

.vale.ini

@@ -0,0 +1,17 @@
+; Vale is a command-line tool that brings code-like linting to prose.
+; More information here: https://docs.errata.ai/vale/about/
+
+StylesPath = styles
+
+Vocab = SAP
+; MinAlertLevel = suggestion
+MinAlertLevel = warning
+
+[formats]
+mdx = md
+
+[*.md]
+BlockIgnores = (<(img|br|Tabs|Redirect|a)[^>]*>)
+BasedOnStyles = Vale, SAP
+
+Vale.Terms = warning

CODE_OF_CONDUCT.md

@@ -1,4 +1,3 @@
-
 # Contributor Covenant Code of Conduct
 
 ## Our Pledge
@@ -11,22 +10,21 @@ We pledge to act and interact in ways that contribute to an open, welcoming, div
 
 Examples of behavior that contributes to a positive environment for our community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall community
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or
+- The use of sexualized language or imagery, and sexual attention or
   advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
   address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
+- Other conduct which could reasonably be considered inappropriate in a professional setting
 
 ## Enforcement Responsibilities
 
@@ -36,11 +34,13 @@ Community leaders have the right and responsibility to remove, edit, or reject c
 
 ## Scope
 
-This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at cloudsdk@sap.com. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [cloudsdk@sap.com](mailto:cloudsdk@sap.com).
+All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 
@@ -50,37 +50,48 @@ Community leaders will follow these Community Impact Guidelines in determining t
 
 ### 1. Correction
 
-**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+**Community Impact**:
+Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
 
-**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+**Consequence**:
+A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate.
+A public apology may be requested.
 
 ### 2. Warning
 
-**Community Impact**: A violation through a single incident or series of actions.
+**Community Impact**:
+A violation through a single incident or series of actions.
 
-**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+**Consequence**:
+A warning with consequences for continued behavior.
+No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time.
+This includes avoiding interactions in community spaces as well as external channels like social media.
+Violating these terms may lead to a temporary or permanent ban.
 
 ### 3. Temporary Ban
 
-**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+**Community Impact**:
+A serious violation of community standards, including sustained inappropriate behavior.
 
-**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+**Consequence**:
+A temporary ban from any sort of interaction or public communication with the community for a specified period of time.
+No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
 
 ### 4. Permanent Ban
 
-**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+**Community Impact**:
+Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
 
-**Consequence**: A permanent ban from any sort of public interaction within the community.
+**Consequence**:
+A permanent ban from any sort of public interaction within the community.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
-available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
 
 [homepage]: https://www.contributor-covenant.org
 
-For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.
-
+For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq.
+Translations are available at https://www.contributor-covenant.org/translations.