Docs/improve readme

.github/workflows/deploy.yml

@@ -19,7 +19,7 @@ jobs:
         uses: DeterminateSystems/nix-installer-action@v4
       - uses: actions/setup-node@v3
         with:
-          node-version: 18
+          node-version: 22
           cache: npm
 
       - name: Install dependencies

.github/workflows/test-deploy.yml

@@ -19,7 +19,7 @@ jobs:
         uses: DeterminateSystems/nix-installer-action@v4
       - uses: actions/setup-node@v3
         with:
-          node-version: 18
+          node-version: 22
           cache: npm
 
       - name: Install dependencies

README.md

@@ -1,12 +1,135 @@
-# Intersect Product Committee
+# Intersect Product Committee Website
 
-Website source code for [Intersect Product Committee](https://product.cardano.intersectmbo.org)
+Official documentation website for the [Intersect Product Committee](https://product.cardano.intersectmbo.org) - a strategic initiative to define and communicate Cardano's Vision 2030.
 
-## Developer shell
+## About
+
+This website serves as the primary platform for the Intersect Product Committee to:
+
+- Share the development of Cardano's long-term vision and strategy
+- Document community workshops and insights from around the world
+- Facilitate transparent collaboration on Cardano's strategic direction
+- Provide a central resource for Vision 2030 proposals and community feedback
+
+## Installation
+
+### Using Nix
+
+Nix is a package manager that simplifies development workflows. It is supported
+on most linux distributions (including NixOS), MacOS and WSL2 on Windows.
+
+Install nix if you do not have it:
 
 ```bash
+curl -fsSL https://install.determinate.systems/nix | sh -s -- install --determinate
+```
+
+Once you have Nix installed:
+
+```bash
+git clone https://github.com/IntersectMBO/product-website.git
 nix develop
 just setup
 just run
 ```
 
+### Using npm (Alternative for users with nodejs experience)
+
+```bash
+# Clone the repository
+git clone https://github.com/IntersectMBO/product-website.git
+cd product-website
+
+# Install dependencies
+npm install
+
+# Start the development server
+npm start
+```
+
+## Prerequisites (if not using nix)
+
+- **Node.js**: Version 20.0 or higher
+- **npm** or **yarn**: Package manager (comes with Node.js)
+- **just**: Run project specific commands
+
+
+
+## Available Scripts
+
+| Command       | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `just setup`  | Install all dependencies locally in `node_modules` dir  |
+| `just run`    | Start the development server at `http://localhost:3000` |
+| `just build`  | Build the website for production                        |
+| `just serve`  | Serve the production build locally                      |
+| `just clear`  | Clear the Docusaurus cache                              |
+
+## Project Structure
+
+```
+product-website/
+├── docs/              # Documentation content (MDX/Markdown files)
+│   ├── vision/       # Vision 2030 documents
+│   └── workshops/    # Workshop summaries and outcomes
+├── src/
+│   ├── components/   # React components
+│   ├── css/          # SCSS stylesheets
+│   └── pages/        # Custom pages
+├── static/           # Static assets (images, fonts, icons)
+├── docusaurus.config.js  # Docusaurus configuration
+└── sidebars.js       # Sidebar navigation structure
+```
+
+## Development Workflow
+
+1. **Start the development server**: `just run`
+2. **Make your changes** to documentation or code
+3. **Preview locally** - changes auto-reload in the browser
+4. **Build to verify**: `just build` to ensure no errors
+5. **Submit a pull request** with your improvements
+
+## Contributing
+
+We welcome contributions! Here are some ways you can help:
+
+- **Documentation**: Improve clarity, fix typos, add examples
+- **Workshops**: Add summaries from community workshops
+- **Design**: Enhance UI/UX, improve accessibility
+- **Code**: Fix bugs, add features, optimize performance
+
+### Making Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature-name`)
+3. Make your changes
+4. Commit with clear messages (`git commit -m "Add: description of changes"`)
+5. Push to your fork (`git push origin feature/your-feature-name`)
+6. Open a Pull Request
+
+## Technology Stack
+
+- **[Docusaurus 3](https://docusaurus.io/)**: Static site generator built with React
+- **React 19**: UI framework
+- **SCSS/Sass**: Styling
+- **Mermaid**: Diagram support
+- **TypeScript**: Type-safe development
+
+## Links
+
+- **Live Website**: https://product.cardano.intersectmbo.org
+- **GitHub Repository**: https://github.com/IntersectMBO/product-website
+- **Intersect**: https://www.intersectmbo.org
+- **Product Committee Docs**: https://productcommittee.docs.intersectmbo.org
+
+## License
+
+Copyright © 2025 Intersect Product Committee
+
+## Support
+
+For questions or issues, please open an issue on GitHub or reach out through the Intersect community channels.
+
+---
+
+Built with ❤️ by the Cardano community using [Docusaurus](https://docusaurus.io/)

justfile

@@ -13,6 +13,12 @@ run:
 build:
     npm run build
 
+serve:
+    npm run serve
+
+clear:
+    npm run clear
+
 # Install npm dependencies
 setup:
     npm install