fix(readme): improve readme and contributing (#824)

Author: dineshpinto

CONTRIBUTING.md

@@ -1,16 +1,16 @@
 # Contributing Guidelines
 
-Thank you for helping improve the **Flare Developer Hub**!  
+Thank you for helping improve **Flare Developer Hub**!
 Your contributions make our documentation, tooling, and examples better for everyone.
 
 We welcome:
 
 - **[GitHub Issues](https://github.com/flare-foundation/developer-hub/issues):** Report bugs, suggest features, or ask questions.
-- **Pull Requests (PRs):** Submit fixes, improvements, or new content (documentation, examples, site features).
+- **[Pull Requests](https://github.com/flare-foundation/developer-hub/pulls):** Submit fixes, improvements, or new content (documentation, examples, site features).
 
 ## 🛠 Development Workflow
 
-1.  **Fork and branch:** Create a branch for your work:
+1.  **Fork and branch:** Fork the repo on GitHub and create a branch for your work:
 
     ```bash
     git checkout -b feature/your-feature-name
@@ -20,7 +20,7 @@ We welcome:
     - Documentation (`docs/`)
     - Source code (`src/`)
     - Examples (`examples/`)
-    - automation scripts (`automations/`, `docgen/`)
+    - automation and docgen scripts (`automations/`, `docgen/`)
 
 3.  **Follow Style Guides:**
     - **Code/Docs:** Run [Pre-PR checks](#pre-pr-checks). Match existing code style.
@@ -66,13 +66,13 @@ We welcome:
 - ✅ **Provide Context:** Describe the problem, solution, and link related issues.
 - ✅ **Pass CI:** Fix any GitHub Actions failures before requesting review.
 - ✅ **Update Docs:** If behavior or usage changes.
-- ✅ **Confirm Licensing:** All PRs are submitted under this repo’s license.
+- ✅ **Confirm Licensing:** All PRs are submitted under this repo’s [license](LICENSE).
 
 ## <a id="pre-pr-checks"></a>🔍 Pre-PR Checks
 
 Run these before submitting a PR:
 
-1. **Build & verify internal links:**
+1. **Build & check internal links:**
 
    ```bash
    npm run build
@@ -90,30 +90,30 @@ Run these before submitting a PR:
    lychee --config lychee.toml .
    ```
 
-4. **If you modified examples**, run their formatters/tests:
-   (example for Rust, see `examples/developer-hub-*/README.md` for more instructions)
+4. **If you modified examples**, run their formatters and tests, see `examples/developer-hub-*/README.md` for more instructions.
+   Example for Rust:
 
    ```bash
    cd examples/developer-hub-rust/
    cargo fmt -- --check # Format
    cargo clippy --bins -- -D warnings # Lint
    cargo build --bins --locked # Build
-   chmod +x test.sh && ./test.sh # Tes
+   chmod +x test.sh && ./test.sh # Test
    ```
 
 ## <a id="diagrams-style-guide"></a>🖼 Diagrams Style Guide
 
 Follow these styles for consistency:
 
-| Element                  | Light Mode | Dark Mode | Notes                                              |
-| :----------------------- | :--------- | :-------- | :------------------------------------------------- |
-| Arrow Width              | `1px`      | `1px`     |                                                    |
-| Arrow Color              | `#595959`  | `#ffffff` |                                                    |
-| Border Width             | `1px`      | `1px`     |                                                    |
-| Border Color (Highlight) | `#e62058`  | `#e62058` | Use for emphasis                                   |
-| Border Color (Normal)    | `#595959`  | `#ffffff` | Default border                                     |
-| Onchain Border Style     | `Solid`    | `Solid`   |                                                    |
-| Offchain Border Style    | `Dashed`   | `Dashed`  | \_Use only if mixing onchain and offchain elements |
+| Element                  | Light Mode | Dark Mode | Notes                                            |
+| :----------------------- | :--------- | :-------- | :----------------------------------------------- |
+| Arrow Width              | `1px`      | `1px`     |                                                  |
+| Arrow Color              | `#595959`  | `#ffffff` |                                                  |
+| Border Width             | `1px`      | `1px`     |                                                  |
+| Border Color (Highlight) | `#e62058`  | `#e62058` | Use for emphasis                                 |
+| Border Color (Normal)    | `#595959`  | `#ffffff` | Default border                                   |
+| Onchain Border Style     | `Solid`    | `Solid`   |                                                  |
+| Offchain Border Style    | `Dashed`   | `Dashed`  | Use only if mixing onchain and offchain elements |
 
 See the [homepage architecture diagram](https://dev.flare.network/#understand-the-architecture) for an example.
 

README.md

@@ -4,8 +4,9 @@ This repository contains the source code and content for the [Flare Developer Hu
 
 This site is built with [Docusaurus](https://docusaurus.io/), a modern static site generator.
 
-> **Note:** This README is for contributors to the Developer Hub source.  
-> If you just want to read the documentation, visit [dev.flare.network](https://dev.flare.network).
+> **Note:**
+> This README is for contributors to Developer Hub.  
+> If you just want to read the docs, visit [dev.flare.network](https://dev.flare.network).
 
 ## 🚀 Getting Started
 
@@ -86,7 +87,8 @@ Language-specific examples use their native formatters:
 - Rust →`cargo fmt` for Rust
 - Python → `ruff` for Python
 
-> **Note:** Prettier support for MDXv3 is evolving ([tracking issue](https://github.com/prettier/prettier/issues/12209)).
+> **Note:**
+> Prettier support for MDXv3 is evolving ([tracking issue](https://github.com/prettier/prettier/issues/12209)).
 > To skip formatting for a section:
 >
 > ```plaintext
@@ -106,8 +108,7 @@ To generate Solidity documentation:
 2. **Run the Documentation Generator:**
 
    ```bash
-   cd docgen
-   chmod +x generate-solidity-docs.sh
+   cd docgen && chmod +x generate-solidity-docs.sh
    ./generate-solidity-docs.sh
    ```
 
@@ -123,7 +124,7 @@ To generate Solidity documentation:
 
 1. **Update addresses and feeds:**
 
-   Fetches latest contract addresses from `ContractRegistry` and feed data for use in site tables and components.
+   Fetches latest contract addresses from `ContractRegistry` and feed data for use in tables and components.
 
    ```bash
    npm run automations
@@ -132,6 +133,7 @@ To generate Solidity documentation:
 2. **Update language dependencies:**
 
    Updates dependencies in all `examples/*` subdirectories.
+   Use with caution, run all test suites after updating.
 
    ```bash
    npm run update-deps
@@ -146,4 +148,4 @@ We welcome contributions of all sizes - from typo fixes to major feature additio
    ```bash
    git checkout -b feature/my-change
    ```
-3. Commit, push, and open a PR.
+3. Commit and push your changes, and open a PR.

examples/developer-hub-go/README.md

@@ -1,6 +1,6 @@
 # developer-hub-go
 
-## Tooling
+## Prerequisites
 
 - [Go](https://go.dev/doc/install)
 - [golangci-lint](https://golangci-lint.run/docs/welcome/install/)

examples/developer-hub-javascript/README.md

@@ -1,6 +1,6 @@
 # developer-hub-javascript
 
-## Tooling (recommended)
+## Prerequisites
 
 - [Node v20](https://nodejs.org/en)
 
@@ -21,3 +21,9 @@ npm run format
 ```bash
 npm run lint
 ```
+
+## Test
+
+```bash
+npm run test
+```

examples/developer-hub-python/README.md

@@ -1,6 +1,6 @@
 # developer-hub-python
 
-## Tooling
+## Prerequisites
 
 - [uv](https://docs.astral.sh/uv/)
 

examples/developer-hub-rust/README.md

@@ -1,13 +1,13 @@
 # developer-hub-rust
 
-## Tooling
+## Prerequisites
 
-- [Rust](https://www.rust-lang.org/tools/install)
+- [Cargo](https://doc.rust-lang.org/cargo/)
 
 ## Install dependencies
 
 ```bash
-cargo build
+cargo build --bins
 ```
 
 ## Format
@@ -19,11 +19,12 @@ cargo fmt
 ## Lint
 
 ```bash
-cargo clippy --fix
+cargo clippy --bins -- -D warnings --fix
 ```
 
 ## Test
 
 ```bash
-cargo test
+chmod +x test.sh
+./test.sh
 ```