docs: fix grammar and syntax issues (#12531)

The commit fixes some grammar and syntax present in our markdown documentation.

Signed-off-by: Vlad Arama <vlad.arama@ericsson.com>

README.md

@@ -15,7 +15,7 @@
   [![Open bugs](https://img.shields.io/badge/Open-bugs-red.svg?style=flat-curved)](https://github.com/eclipse-theia/theia/labels/bug)
   [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/eclipse-theia/theia)
 
-Eclipse Theia is an extensible framework to develop full-fledged multi-language Cloud & Desktop IDEs and tools with  state-of-the-art web technologies.
+Eclipse Theia is an extensible framework to develop full-fledged multi-language Cloud & Desktop IDEs and tools with state-of-the-art web technologies.
 
 </div>
 

doc/Developing.md

@@ -371,7 +371,7 @@ You should be able to see message of `[${server-name}: ${server-PID}]: IPC start
 ### Debug the plugin host
 
   - Pass `--hosted-plugin-inspect=9339` arg to the backend server from the command line.
-    - Instead you can run `Launch Browser Backend` launch configuration which is already pre-configured.
+    - Instead, you can run `Launch Browser Backend` launch configuration which is already pre-configured.
   - Open the debug view and run the `Attach to Plugin Host` launch configuration.
     - It connects to the plugin host if at least one extension is detected, otherwise it timeouts after 60s.
     - If you want to debug the activation then enable `stopOnEntry` flag.
@@ -382,7 +382,7 @@ You should be able to see message of `[${server-name}: ${server-PID}]: IPC start
 
 [click for base article](https://github.com/eclipse-theia/theia/issues/3251#issuecomment-468166533)
 
-The following launch configuration is meant to be used when the Theia project is opened as the main project in vscode, the following launch configuration is added inside .vscode/launch.json.
+The following launch configuration is meant to be used when the Theia project is opened as the main project in VS Code, the following launch configuration is added inside .vscode/launch.json.
 - The source repository of your plugin is expected under your `${workspaceFolder}/plugins` folder
 - You can start the frontend from URL: http://localhost:3030
 - It's suggested to update your frontend launch configuration URL to open your favorite target project in a second launch
@@ -566,10 +566,10 @@ errors while building, testing or running the application then;
  try to disable (or uninstall) your anti-malware software.
  See [here](https://github.com/npm/npm/issues/13461#issuecomment-282556281).
  - Still having issues on Windows? File a [bug]. We are working on Linux or OS X
- operating systems. Hence we are more than happy to receive any Windows-related
+ operating systems. Hence, we are more than happy to receive any Windows-related
  feedbacks, [bug](https://github.com/eclipse-theia/theia/issues) reports.
 
-If you're still struggling with the build but you use Windows 10, the you can enable the `Windows Subsystem for Linux` and you can get a Linux distro for free.
+If you're still struggling with the build, but you use Windows 10, then you can enable the `Windows Subsystem for Linux` and you can get a Linux distro for free.
 
 ### macOS
 

doc/Migration.md

@@ -49,9 +49,9 @@ For example:
 
 #### Disabled node integration and added context isolation flag in Electron renderer
 
-This also means that `electron-remote` can no longer be used in components in `electron-frontend` or `electron-common`. In order to use electron-related functionality from the browser, you need to expose an API via a preload script (see  https://www.electronjs.org/docs/latest/tutorial/context-isolation). to achieve this from a Theia extension, you need to follow these steps:
+This also means that `electron-remote` can no longer be used in components in `electron-frontend` or `electron-common`. In order to use electron-related functionality from the browser, you need to expose an API via a preload script (see https://www.electronjs.org/docs/latest/tutorial/context-isolation). To achieve this from a Theia extension, you need to follow these steps:
 
-1. Define the API interface and declare an api variable on the global `window` variable. See `packages/filesystem/electron-common/electron-api.ts` for an example
+1. Define the API interface and declare an API variable on the global `window` variable. See `packages/filesystem/electron-common/electron-api.ts` for an example
 2. Write a preload script module that implements the API on the renderer ("browser") side and exposes the API via `exposeInMainWorld`. You'll need to expose the API in an exported function called `preload()`. See `packages/filesystem/electron-browser/preload.ts` for an example.
 3. Declare a `theiaExtensions` entry pointing to the preload script like so:
 ```
@@ -70,7 +70,7 @@ See `/packages/filesystem/package.json` for an example
   }
 ```
 
-If you are using nodejs API in your electron browser-side code you will also have to move the code outside of the renderer process, for example
+If you are using NodeJS API in your electron browser-side code you will also have to move the code outside of the renderer process, for example
 by setting up an API like described above, or, for example, by using a back-end service.
 
 ### v1.35.0
@@ -186,7 +186,7 @@ For more details, see the socket.io documentation about [using multiple nodes](h
 
 #### Resolutions
 
-Due to a [colors.js](https://github.com/Marak/colors.js) issue, a [resolution](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) may be necessary for your application in order to workaround the problem:
+Due to a [colors.js](https://github.com/Marak/colors.js) issue, a [resolution](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) may be necessary for your application in order to work around the problem:
 
 For example:
 
@@ -267,7 +267,7 @@ You can delete this whole block and replace it by the following:
 
 #### Keytar
 
-- [`keytar`](https://github.com/atom/node-keytar) was added as a dependency for the secrets API. and may require `libsecret` in your particular distribution to be functional:
+- [`keytar`](https://github.com/atom/node-keytar) was added as a dependency for the secrets API. It may require `libsecret` in your particular distribution to be functional:
   - Debian/Ubuntu: `sudo apt-get install libsecret-1-dev`
   - Red Hat-based: `sudo yum install libsecret-devel`
   - Arch Linux: `sudo pacman -S libsecret`

doc/Plugin-API.md

@@ -25,8 +25,8 @@ The report can be found here:
 
 - [plugin](https://github.com/eclipse-theia/theia/tree/master/packages/plugin): Contains the API declaration of the theia plugin namespace
 - [plugin-ext](https://github.com/eclipse-theia/theia/tree/master/packages/plugin-ext): Contains both the mechanisms for running plugins and providing them with an API namespace and the implementation of the ‘theia’ plugin API
-- [plugin-ext-vscode](https://github.com/eclipse-theia/theia/tree/master/packages/plugin-ext-vscode): Contains an implementation of the vscode plugin API.
-Since vscode and Theia API’s are largely compatible, the initialization passes on the Theia plugin API and overrides a few members in the api object to be compatible to vscode extensions (see [plugin-ext-vscode/src/node/plugin-vscode-init.ts](https://github.com/eclipse-theia/theia/blob/master/packages/plugin-ext-vscode/src/node/plugin-vscode-init.ts))
+- [plugin-ext-vscode](https://github.com/eclipse-theia/theia/tree/master/packages/plugin-ext-vscode): Contains an implementation of the VS Code plugin API.
+Since VS Code and Theia APIs are largely compatible, the initialization passes on the Theia plugin API and overrides a few members in the API object to be compatible to VS Code extensions (see [plugin-ext-vscode/src/node/plugin-vscode-init.ts](https://github.com/eclipse-theia/theia/blob/master/packages/plugin-ext-vscode/src/node/plugin-vscode-init.ts))
 
 ## API definition and exposure
 
@@ -167,19 +167,19 @@ Another example to browse are the [TaskExtImpl](https://github.com/eclipse-theia
 ### Adding new types
 
 New classes and other types such as enums are usually implemented in [plugin-ext/src/plugin/types-impl.ts](https://github.com/eclipse-theia/theia/blob/master/packages/plugin-ext/src/plugin/types-impl.ts).
-They can be added here and the added to the api object created in the API factory.
+They can be added here and the added to the API object created in the API factory.
 
 ## Additional Links
 
 Talk by Thomas Maeder on writing plugin API: <https://www.youtube.com/watch?v=Z_65jy8_9SM>
 
-Adding a new plugin api namespace outside of theia plugin api: [how-to-add-new-plugin-namespace.md](https://github.com/eclipse-theia/theia/blob/master/packages/plugin-ext/doc/how-to-add-new-plugin-namespace.md)
+Adding a new plugin API namespace outside of theia plugin API: [how-to-add-new-plugin-namespace.md](https://github.com/eclipse-theia/theia/blob/master/packages/plugin-ext/doc/how-to-add-new-plugin-namespace.md)
 
 Theia Plugin Implementation wiki page: <https://github.com/eclipse-theia/theia/wiki/Theia-Plugin-Implementation>
 
 Writing Plugin API wiki page in the che wiki: <https://github.com/eclipse/che/wiki/Writing-Theia-plugin-API>
 
-Theia vs VS Code API Comparator: <https://github.com/eclipse-theia/vscode-theia-comparator>
+Theia versus VS Code API Comparator: <https://github.com/eclipse-theia/vscode-theia-comparator>
 
 Theia's extension mechanisms: VS Code extensions, Theia extensions, and Theia plugins: <https://theia-ide.org/docs/extensions>
 

doc/Publishing.md

@@ -20,8 +20,8 @@ Before a release (Monday of the same week), it is a good time to perform a `yarn
 Updating the `yarn.lock` helps identify potential problems with our dependency version ranges, and is more representative of what downstream adopters may pull when building their own applications.
 
 To successfully complete a `yarn upgrade`, one must:
-- perform `yarn upgrade` at the root of the repository.
-- fix any compilation errors, typing issues, and failing tests that may be introduced.
+- Perform `yarn upgrade` at the root of the repository.
+- Fix any compilation errors, typing issues, and failing tests that may be introduced.
 
 ## Announce Release
 
@@ -51,7 +51,7 @@ Here is an [example](https://community.theia-ide.org/t/0-11-0-release/373).
 
 ## Pre-Publishing Steps
 
-Before publishing it's important to make sure that a functional Theia application can be made from the latest `next` version of the platform. Else we will have problems with "latest" after publishing.
+Before publishing, it's important to make sure that a functional Theia application can be made from the latest `next` version of the platform. Else we will have problems with "latest" after publishing.
 
 - Update the forum release post to ask committers to hold-off merging any PR while the release is ongoing.
 
@@ -95,11 +95,11 @@ The next step is to create a new [**Release**](https://github.com/eclipse-theia/
 This will create a new `tag`, `release` with the appropriate assets (`.zip`, `tar.gz`) and notify subscribers.
 
 In order to create a new release, one must:
-- navigate to the releases [page](https://github.com/eclipse-theia/theia/releases).
-- select the _"Draft a new release"_ button.
-- input the appropriate release `tag` version (ex: `v1.2.0`).
-- input the appropriate release `name` (ex: `Eclipse Theia v1.2.0`).
-- include a release `description` to include a reference to the `changelog` at the respective `sha` and release version:
+- Navigate to the releases [page](https://github.com/eclipse-theia/theia/releases).
+- Select the _"Draft a new release"_ button.
+- Input the appropriate release `tag` version (ex: `v1.2.0`).
+- Input the appropriate release `name` (ex: `Eclipse Theia v1.2.0`).
+- Include a release `description` to include a reference to the `changelog` at the respective `sha` and release version:
 
    ```md
    [Release Changelog](https://github.com/eclipse-theia/theia/blob/${sha}/CHANGELOG.md#${changelog-version-header})
@@ -111,13 +111,13 @@ In order to create a new release, one must:
    [Release Changelog](https://github.com/eclipse-theia/theia/blob/2aa2fa1ab091ec36ef851c4e364b322301cddb40/CHANGELOG.md#v120)
    ```
 
-- include a reference to the migration guide in the release description:
+- Include a reference to the migration guide in the release description:
 
    ```md
    [Migration Guide](https://github.com/eclipse-theia/theia/blob/master/doc/Migration.md)
    ```
 
-- select _"Publish Release"_ bottom at the bottom of the page.
+- Select _"Publish Release"_ bottom at the bottom of the page.
 
 For additional information, please consult the official GitHub documentation regarding [creating releases](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release).
 
@@ -133,7 +133,7 @@ Login to [Eclipse Foundation Theia project page]( https://projects.eclipse.org/p
 
     Select the edit tab
     - In "The Basic" section
-        - Select the  "Type A" in the IP Due Diligence type.
+        - Select the "Type A" in the IP Due Diligence type.
     - In the "Project Plan"
         - Deliverables section
             - Paste the content of the changelog.md.

doc/api-management.md

@@ -74,7 +74,7 @@ export interface StableInterface {
 
 - All new APIs should always be added as **experimental** since it's almost impossible to get [stable API](#stable) right the first time.
 - Experimental APIs don't require the stability tag, but if a new member is added to [stable API](#stable) then it should be explicitly annotated.
-- Experimental APIs don't require extensive documentation. It does not mean that one should not document not obvious parts.
+- Experimental APIs don't require extensive documentation. It does not mean that one shouldn't document unobvious parts.
 - Experimental APIs don't follow [semver](https://semver.org/#spec-item-8) semantic.
 - Experimental APIs could be changed or removed without [the deprecation cycle](#deprecation) if they were not widely adopted.
 - Adoption should be measured by the number of internal clients or based on the feedback of Theia contributors and committers.