update

Author: mrtnzlml

README.md

@@ -1,48 +1,103 @@
 # The Solution Architect's Handbook
 
+This repository contains the source code for "The Solution Architect's Handbook," a Docusaurus-based website with documentation and resources for Solution Architects working with Rossum.ai.
+
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-## Run the website locally
+## Getting Started
 
-First, install dependencies:
+To get a local copy up and running, follow these simple steps.
 
-```
-yarn
-```
+### Prerequisites
 
-Then, run it:
+You need to have [Yarn](https://yarnpkg.com/) installed on your machine.
 
-```
+### Installation
+
+1.  Clone the repo:
+    ```sh
+    git clone https://github.com/mrtnzlml/rossum-sa-handbook.git
+    ```
+2.  Install Yarn packages:
+    ```sh
+    yarn
+    ```
+
+### Running the development server
+
+To start the development server, run:
+
+```sh
 yarn start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-## Run tests locally
+## Running Tests
 
-```
-yarn playwright test [--ui]
+This project uses [Playwright](https://playwright.dev/) for end-to-end testing. To run the tests, use the following command:
+
+```sh
+yarn playwright test
 ```
 
-If needed, you can also build the website locally:
+You can also open the Playwright UI to view and debug tests:
 
+```sh
+yarn playwright test --ui
 ```
+
+## Building and Serving Locally
+
+To create a static build of the website, run:
+
+```sh
 yarn build
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service or locally via `yarn serve`.
+This command generates static content into the `build` directory.
+
+You can serve the built site locally using:
+
+```sh
+yarn serve
+```
+
+This is a great way to check the production build before deploying.
+
+## Deployment
+
+This website is deployed to GitHub Pages. The deployment is handled automatically by a GitHub Actions workflow.
+
+You can also trigger a manual deployment by running:
+
+```sh
+yarn deploy
+```
+
+## Content Management
 
-## Archiving and deprecating pages
+### Archiving and Deprecating Pages
 
-1. Use `<Deprecated />` tag on all the relevant pages
-1. Move the page as is into the `deprecated` folder
-1. Adjust any broken links and imports
-1. Add `slug` into the [front matter](https://docusaurus.io/docs/create-doc#doc-front-matter) (to remove the `/deprecated/` path from the URL for backwards compatibility)
+When a page is no longer relevant, it should be archived. Follow these steps:
 
-## Collecting all documentation into one file
+1.  Use the `<Deprecated />` tag on the relevant page(s).
+2.  Move the page into the `docs/learn/deprecated` folder.
+3.  Adjust any broken links and imports.
+4.  Add a `slug` to the [front matter](https://docusaurus.io/docs/create-doc#doc-front-matter) to remove the `/deprecated/` path from the URL for backwards compatibility. For example: `slug: /my-old-url`.
 
-Very handy for Gemini gems:
+### Collecting All Documentation
+
+For tasks that require all documentation content in a single file (like training AI models), you can use this handy script:
 
 ```bash
 find ./docs ./cookbook -name "*.md" | xargs cat > ./all_handbook_content.txt
 ```
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
+
+The documentation source files are located in the `/docs` directory. You can edit them directly in GitHub by clicking the "Edit this page" link at the bottom of each documentation page, or by navigating to the file in the repository.