update documentation for docs/

Signed-off-by: Mehdi Nassim KHODJA <[email protected]>

docs/README.md

@@ -1,31 +1,34 @@
-# Docs Readme
+# Docs
+
+This folder contains the documentation for the Armada project. The documentation is written in markdown and is rendered as webpages on [armadaproject.io](https://armadaproject.io).
+
+It's accessible from the IDE, GitHub, and the website.
 
 ## For Developers
 
 See [website.md](./developer/website.md)
 
 ## Overview
-Docs added to this directory are automatically copied into armadaproject.io.
+
+Docs added to this the `docs/` folder are automatically copied into [armadaproject.io](https://armadaproject.io).
 
 For example, if you wanted to document bananas, and you added `bananas.md`,
 once committed to master that would be published at
 `https://armadaproject.io/bananas/`.
 
-## Complex pages with assets
-If you'd like to add a more complex page, such as one with images or other
-linked assets, you have to be very careful to ensure links will work both
-for people viewing in github and for those viewing via armadaproject.io.
+> [!NOTE]  
+> All files in `docs/` folder are rendered as webpage except this `README.md` file.
 
-The easiest way to accomplish this is by using page bundles. See quickstart
-as as example: quickstart/index.md is the actual content, with links to
-various images using relative pathing; e.g. `./my-image.png`. This is
-considered a page bundle by jekyll (github pages) and are rendered as a
-single page at `quickstart/`.
+## Pages with assets
 
-In order to get this page bundle pushed to gh-pages branch, you'll need
-to adjust the github workflow in `.github/workflows/pages.yml` to add your
-new page bundle as well.
+If you'd like to add a more complex page, such as one with images or other
+linked assets, you have to be careful to ensure links will work both
+for people viewing in GitHub and for those viewing via [armadaproject.io](https://armadaproject.io).
+
+The easiest way to accomplish this is by using page bundles. Assets should be located inside the `docs/` folder and
+used in the markdown file with relative paths.
 
 ## Removing pages
-If you put a commit here to remove a page, you will need to also commit
-to the gh-pages branch to remove that page.
+
+Any page that is removed from the `docs/` folder will be removed from the website automatically. The `docs/` folder is
+the source of truth for the website's content.