doc: update working on docs

doc/working-on-docs.md

@@ -7,24 +7,68 @@
 * This can also be executed via `gulpfile.js` task `fetch`, by running `gulp fetch` which pulls in the files to `dev/en/{file dest}`.
 * Most auto-generated files have a comment tag at the top of the file to indicate that they come from elsewhere.
 
-## Update latest (x.y) from `dev`
+## Update current docs from `dev`
 
-Normal build doesn't update latest (7.x) from dev version of docs. You will need to do this manually using `gulp snapshot`. Read more [here](https://github.com/apache/cordova-docs/blob/master/gulpfile.js#L212).
+The following command can quickly sync the `dev` docs with the current latest docs:
 
-## Create new version of the docs
+```bash
+npm run update-docs
+```
 
-To increment the documentation version (e.g. `X.X.X`, either use the gulp task:
+Read more [here](https://github.com/apache/cordova-docs/blob/master/gulpfile.js#L212).
 
-    gulp newversion --version X.X.X
+## Create new snapshot from `dev`
 
-or manually run the `incrementversion.js` script:
+The following commands can be used to create a new snapshot of `dev` docs:
 
-    node ./tools/bin/incrementversion.js www/docs X.X.X
+```bash
+npx gulp newversion
+npx gulp newversion --bumpCli
+```
 
-To only run for a specific language (__this should only happen when translation is intentionally left out for a given version__), specify the language to the Gulp task as follows:
+Please read the section, [Preparing Doc Release Scenarios](#Preparing-Doc-Release-Scenarios), below to understand which command fits your scenario.
 
-    gulp newversion --version X.X.X --language YY
+## Preparing Doc Release Scenarios
 
-or manually, to the script, as follows:
+When preparing to release docs, there are two things to be aware of, the version of Cordova CLI and if the changes warrants for a new doc version.
 
-    node ./tools/bin/incrementversion.js www/docs X.X.X YY
+Here are a few scenarios that will help decide how if we are updating an existing snapshot of creating a new one.
+
+1. Are we preparing to release new docs because there was a major release of Cordova CLI?
+
+    If the answer is **yes**, then we will be creating a new version of docs with the following command:
+
+    ```bash
+    npx gulp newversion --bumpCli
+    ```
+
+    If the current released docs version is `12.x` and we are preparing for Cordova-CLI 13.x, the above command will create `13.x-2024.10`.
+
+    > Notice: The year and month will be appended automatically.
+
+2. Are we preparing to release new docs because there was a minor or patch release of Cordova CLI?
+
+    If the answer is **yes**, then we do not need to make a new snapshot. In this case, we can update an existing snapshot with the following command:
+
+    ```bash
+    npm run update-docs
+    ```
+
+    > Notice: In this scenario we are expecting the version to already exist. If it was missing, then we would have to create a new snapshot but in most cases it should never be missing.
+
+3. Are we preparing docs for a major release to one or more of Cordova's platforms while the CLI version was unchanged?
+
+    If the answer is **yes**, then we need to make a new snapshot, but we do not need to bump the CLI major. We can do this with the following command:
+
+    ```bash
+    npx gulp newversion
+    ```
+
+    If the current doc snapshot is `12.x`, then the above command will create a new snapshot with the same CLI major version but the appended date will be different.
+
+    E.g. `12.x-2024.10`
+
+    > Notice:
+    >
+    > *`12.x` and older does not have date appended. Any newly created snapshots will append the date value.
+    > * If we already have `12.x-2024.10` and the month is still the same, we should use senario 2. `npm run update-docs`.