enhance www/README.md

www/README.md

@@ -1,44 +1,88 @@
-# Website
+# Skip Documentation Website
 
-The documentation website is built using [Docusaurus](https://docusaurus.io/).
+This website is built using [Docusaurus](https://docusaurus.io/) and hosts both our documentation and blog.
 
+## API Documentation
 
-# API Documentation
+The API documentation is generated using:
+- [TypeDoc](https://typedoc.org/index.html) for API documentation generation
+- [docusaurus-plugin-typedoc](https://typedoc-plugin-markdown.org/plugins/docusaurus) for Docusaurus integration
 
-The API docs are generated by [TypeDoc](https://typedoc.org/index.html) and integrated into docusaurus using [docusaurus-plugin-typedoc](https://typedoc-plugin-markdown.org/plugins/docusaurus).
-This setup needs the development/source docs site to be in the same repo as the sources, as there are relative paths in the docusaurus config file to the sources.
-A separate deployment step will be needed to generate the docs and push them to the repo that feeds the live site.
-This also means that we can iterate on the docs in the source repo without publishing them immediately, and then choose to publish them in sync with publishing packages.
+### Development Setup
 
-The workflow for working on API docs is:
-```
-- $ cd /path/to/repo/root
-- $ make docs                           # to initialize the api docs
-- $ make docs-run                       # to run the docs site locally
-- visit http://localhost:3000/docs/api/core
-- edit the doc comments in the sources
-- $ make docs                           # to regenerate the api docs
+The development/source docs site must be in the same repository as the source code due to relative paths in the Docusaurus configuration. This setup allows us to:
+- Iterate on documentation in the source repository
+- Choose when to publish documentation
+- Keep documentation in sync with package releases
+
+### Development Workflow
+
+#### Standard Workflow
+```bash
+# From repository root INSIDE your Docker instance
+make docs           # Initialize API documentation
+
+# From repository rood OUTSIDE your Docker instance
+make docs-run       # Run the docs site locally
+# Visit http://localhost:3000/docs/api/core or http://localhost/blog
+
+# After editing doc comments in the sources
+make docs           # Regenerate API documentation
 ```
+
 A faster but not robust way to regenerate the api docs is:
+```bash
+cd /path/to/repo/root/www && npx docusaurus generate-typedoc
 ```
-- cd /path/to/repo/root/www && npx docusaurus generate-typedoc
-```
-To publish the docs to the live site:
-```
-- $ make docs-publish
+
+### Publishing Documentation
+
+Before, commit your changes and send them for review
+```bash
+git add <your_files>
+git commit -m '<some message>'
+gh pr create # if you use the GitHub CLI
 ```
-This will suggest to run:
+
+When reviewed and merged, you are ready to publish documentation to the live site:
+```bash
+# From repository root INSIDE your Docker instance
+make docs-publish
 ```
+
+You should eventually read: 
+```bash
 Test locally: make docs-serve
 Push to live site: cd www/docs_site/; git add -A; git commit -m 'update to <commit>'; git push; cd -
 ```
-Note that the docs_site commit messages will mention the wrong commit hashes if `make docs-publish` is run from a commit that is not (an ancestor of) `main`.
 
-The documentation for the tags that TypeDoc recognizes is
-[here](https://typedoc.org/guides/tags/).
+The commit hash in the last line should be the hash of your commit in the skip repository. 
+
+> **Note**: If `make docs-publish` is run from a commit that is not (an ancestor of) `main`, the docs_site commit messages will contain incorrect commit hashes.
+
+## Documentation Structure
+
+- The markdown documentation under `www/docs` can be edited while the site is running at http://localhost:3000
+- Changes to the `www/docs` file structure must be reflected in `www/sidebars.ts`
+- The `docusaurus.config.ts` file is sensitive to the file system locations of source entry points and tsconfig files
 
-Once the docs site is running at http://localhost:3000, the markdown documentation under `www/docs` can be edited and the changes are usually picked up automatically.
+## TypeDoc Tags
 
-Changes to the `www/docs` file structure usually need to be reflected in the `www/sidebars.ts` file.
+You may refer to the [official documentation](https://typedoc.org/guides/tags/) of TypeDoc tags for more information.
 
-The `docusaurus.config.ts` file is sensitive to the file system locations of the source entry points and tsconfig files.
+
+## FAQ
+
+### What if my `docs_site` is not on the `main` branch ?
+Clean up your repository is good idea at this point and then start the process again:
+```bash
+git pull --rebase  # ensure that your local docs_site submodule is up-to-date
+git clean -Xdn     # -n for a dry-run and double-check what's to be cleaned out
+git clean -Xdf     # the actual cleaning
+```
+
+### What if the hash in the suggested commit message is not the hash of your commit? 
+You can get it from the skip repository: 
+```bash
+git rev-parse --short HEAD # supposingly it is the last commit of the branch
+```