DOC-3220: Update the README.md file for tinymce/docs project to include updated information. (#3733) (#3800)

* DOC-3220: Update the `README.md` file for `tinymce/docs` project to include updated information. (#3733)

* DOC-3220: Update the README.md file for tinymce/docs to include updated information.

* Update README.md

* Update README.md

* Update README.md

Co-authored-by: tiny-ben-tran <[email protected]>

* Update README.md

Co-authored-by: Shan <[email protected]>

---------

Co-authored-by: tiny-ben-tran <[email protected]>
Co-authored-by: Shan <[email protected]>

Author: 3 people

README.md

@@ -1,119 +1,101 @@
-# TinyMCE documentation
+# TinyMCE Documentation
 
-This project maintains the documentation for TinyMCE at
-[https://www.tiny.cloud/docs](https://www.tiny.cloud/docs). If you have any
-modifications you wish to contribute, fork this project, make the changes
-and submit a pull request. You will need to sign the contributor’s license
-agreement, which will be emailed to you upon creating the pull request.
+This project maintains the official documentation for TinyMCE, available at [https://www.tiny.cloud/docs](https://www.tiny.cloud/docs). If you have modifications or improvements to contribute, fork this repository, make the necessary changes, and submit a pull request (PR). A contributor's license agreement (CLA) must be signed before your contribution can be merged. This agreement will be sent via email when you create a PR.
 
-This project is built using [Antora](https://antora.org/).
+This project is built using [Antora](https://antora.org/)
 
 ## Contributing to the TinyMCE Documentation
 
-If you would like to contribute to the TinyMCE project please read the TinyMCE Documentation Contributor’s Guide at either:
+To contribute to the TinyMCE documentation project, please review the following resources:
 
-- [TinyMCE Documentation - Contributor's Guide](https://www.tiny.cloud/docs/configure/contributing-docs/).
-- [GitHub - How to contribute to TinyMCE’s documentation](https://github.com/tinymce/tinymce-docs/blob/release/docs-6/CONTRIBUTING.md#how-to-contribute-to-tinymces-documentation).
+- [GitHub - How to contribute to TinyMCE’s documentation](https://github.com/tinymce/tinymce-docs/blob/main/CONTRIBUTING.md#how-to-contribute-to-tinymces-documentation)
 
-## Working on TinyMCE documentation
+These guides cover contribution guidelines, project structure, style conventions, and best practices for submitting changes.
 
-### Compiling or building the documentation
+## Setting Up Your Development Environment
 
-The following procedure assists with building (or compiling) the documentation locally. Tiny recommends testing and reviewing changes locally prior to submitting a pull request.
+To contribute effectively, you should set up a local development environment. This allows you to preview and test your changes before submitting a PR.
 
-#### Installing Prerequisites
+### Prerequisites
 
-##### Linux users
+Ensure the following software is installed:
 
-You need the following programs installed on your computer:
+- [Node.js](https://nodejs.org/en/) (version 22.9 or lower)
+- [Yarn](https://yarnpkg.com/)
+- Git
 
-#### First time set up
+### Cloning the Repository
 
-Once you have installed any missing prerequisites, in a terminal or on a command prompt:
+Clone the TinyMCE documentation repository:
 
-1. Clone the git repository:
-    ```
-    git clone [email protected]:tinymce/tinymce-docs.git
-    ```
-
-2. Change directory into the cloned git repository:
-    ```
-    cd tinymce-docs
-    ```
-
-3. Run yarn install
-    ```
-    yarn install
-    ```
+```bash
+git clone [email protected]:tinymce/tinymce-docs.git
+cd tinymce-docs
+yarn
+```
 
-#### Run the development version of the documentation
+### Running the Development Server
 
-To create a development version of the documentation, run:
+To build and serve the documentation locally:
 
-```
+```bash
 yarn build
-yarn serve
+yarn start-dev
 ```
 
+Visit [http://127.0.0.1:4000](http://127.0.0.1:4000) to view the documentation. The server supports hot-reloading, so changes will automatically reflect when you save your work.
 
-To view the documentation; in a web browser, navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000).
-
-> **Note**: The development version of the documentation will update automatically when you save changes locally.
+> **Note:** The `yarn build` command generates the API reference documentation from the TinyMCE source code. To adjust the API version, edit the `API_VERSION` variable in the `scripts/api-reference.sh` file. Alternatively, use `yarn build-local` to build using a local TinyMCE instance:
 
-The `yarn build` step will download the latest TinyMCE package and generate new API reference content from source code. To change the version of TinyMCE API, open the `-scripts/api-reference.sh` file and edit the API_VERSION to the TinyMCE version you would like to generate API docs for.  Alternatively, to build using a local version of TinyMCE, `yarn build-local ../path/to/local/TinyMCE`.
+Example:
 
-> **Note**: The development server does not need to be stopped prior to running the `yarn build` command, antora should pick up the new changes generated by the build step.
+```bash
+yarn build-local ../path/to/local/tinymce
+```
 
-#### TinyMCE API documentation
+### API Documentation
 
-The TinyMCE API documentation is maintained within the [TinyMCE project repository](https://github.com/tinymce/tinymce) and compiled for the documentation site using [MoxieDoc](https://github.com/tinymce/moxiedoc).
+The TinyMCE API documentation is compiled and generated using [MoxieDoc](https://github.com/tinymce/moxiedoc) from the core [TinyMCE project repository](https://github.com/tinymce/tinymce). To update the published API docs:
 
-To update the published API documentation:
+1. Update the `.api-version` file.
+2. Run `yarn build`:
 
-1. Change the version in `.api-version`.
-2. Run `yarn build`.
+   * Running `yarn build` downloads the TinyMCE package specified in `.api-version` and generates new API reference content from source.
 3. Commit the changes.
 
-Running `yarn build` downloads the TinyMCE package specified in `.api-version` and generates new API reference content from source.
+> **Warning:** The API documentation should not be edited manually. Always generate it from source to ensure accuracy.
 
-**Note:** The API documentation should never be edited manually.
+## Live Demos
 
-##### Prerequisites
+Live demos can be added to the `modules/ROOT/examples/live-demos` directory. Reference them in your documentation with:
 
-- [Node.js](https://nodejs.org/en/).
-
-
-### Live Demos
+```asciidoc
+liveDemo::{sub-directory-name}[]
+```
 
-New live demos can be added to the [modules/ROOT/examples/live-demos directory](modules/ROOT/examples/live-demos). It then can be referenced in your doc with the following code:
+### Overriding the TinyMCE URL in Live Demos
 
-```
-  liveDemo::{sub-directory-name}[]
-```
+By default, live demos load TinyMCE from the URL specified in the `tinymce_live_demo_url` attribute in the `antora.yml` file. This can be overridden for specific use cases:
 
-#### Overriding the tinymce URL in live demos
+* Testing a new feature on the `dev` channel.
+* Running the site locally while testing live demos on a different channel.
 
-All live demos usually get their `tinymce.min.js` URL from the `tinymce_live_demo_url` setting in the `antora.yml` file.
-However, there are some instances where you wish to override this, e.g.
+To help with this, there are two mechanisms for overriding the `tinymce.min.js` URL:
 
- - You want to push/deploy a branch for a new feature that's only on the 'dev' channel.
- - You want to run the site locally, but test out the live demos in a different channel.
+1. **Global Override:**
+   To change the TinyMCE URL for all live demos, modify the `tinymce_live_demo_url` attribute in `antora-playbook-dev.yml`:
 
-To help with this, there are two mechanisms for overriding the `tinymce.min.js` URL.
+   ```yaml
+   asciidoc:
+     attributes:
+       tinymce_live_demo_url: https://your-custom-url.com/tinymce.min.js
+   ```
 
- 1. Change the URL for all live demos by setting the `tinymce_live_demo_url` attribute in `antora-playbook-dev.yml`. For example:
-    ```
-      asciidoc
-        attributes:
-          tinymce_live_demo_url: URL_to_script_file
-    ```
+2. **Per-Demo Override:**  Use the `script_url_override` attribute:
+   To override the URL for a specific live demo:
 
- 2. Change the URL for an individual live demo by setting `script_url_override` attribute in the live demo markup. For example:
-    ```
-      liveDemo::{sub-directory-name}[script_url_override='URL_to_script_file']
-    ```
+   ```asciidoc
+   liveDemo::{sub-directory-name}[script_url_override='https://your-custom-url.com/tinymce.min.js']
+   ```
 
-    - This is useful if you want to deploy the develop branch for a feature only in the 'dev' channel.
-    - This only overrides the URL for one live demo.
-    - Don't use this in more than one live demo on a page.
-    - Don't use this long-term - when the feature is fully rolled-out, use the standard channel.
+> **Caution:** Use this sparingly. Avoid using different URLs for multiple demos on the same page, and remember to revert these changes once the feature is fully released.