docs: rewrite README for beginner-friendly onboarding

README.md

@@ -1,61 +1,129 @@
 # DevHub
 
-The official website for the DevHub developer community. Built with Next.js, TypeScript, and Tailwind CSS.
+The official website for DevHub, a developer community focused on helping people learn, build, and connect with other developers. This repository contains the source code for the website, including the landing page, community rules, guides, resource library, articles, and partners page.
+
+If you're new here, welcome! This README is designed to guide you from cloning the repository to making your first contribution, even if you've never worked with this codebase before.
+
+## About DevHub
+
+DevHub is a developer community focused on helping programmers learn, collaborate, and grow together.
+
+The website brings together community resources in one place, including:
+
+- 📚 Learning guides for developers
+- 🛠️ Curated tools and useful resources
+- 📖 Articles and tutorials
+- 🤝 Community information and onboarding guides
+- 📜 Rules, FAQs, and moderation guides
+- ❤️ Open-source contribution opportunities
+
+If you're new to open source, this project is a great place to start because documentation improvements, bug fixes, and feature enhancements are all welcome.
 
 ## What's in here
 
-- Landing page
-- Community guides
-- Resource library, curated tools and learning materials
-- Partners page
-- DevHub Pages:
-  - Getting Started
-  - Join Guide
-  - Server Info
-  - How to Ask
-  - How to Help
-  - Code of Conduct
-  - Contributing
-  - Moderation Guide
-  - Staff Roles
-  - FAQ
-  - and many many more
+- Landing page: introduction to DevHub and what the community offers
+- Pages: guides like Getting Started, How to Ask, How to Help, Code of Conduct, Contributing, Moderation Guide, Staff Roles, FAQ, and more
+- Resource library: curated tools and learning materials
+- Articles: write-ups from the community
+- Rules: the server and community rules in one place
+- Partners: communities and projects DevHub partners with
 
 ## Tech Stack
 
-- **Framework** - Next.js
-- **Language** - TypeScript
-- **Styling** - Tailwind CSS
-- **Animation Libriary** - GSAP and Framer Motion
-- **Component Libriary** - React Bits
-- **Icons** - Lucide
-- **Deployment** - Vercel
+| Technology           | Purpose                                   |
+| -------------------- | ----------------------------------------- |
+| Next.js              | React framework used to build the website |
+| TypeScript           | Adds static typing to JavaScript          |
+| Tailwind CSS         | Utility-first CSS framework for styling   |
+| GSAP & Framer Motion | Animation libraries                       |
+| React Bits           | UI component library                      |
+| Lucide               | Icon library                              |
+| Vercel               | Deployment platform                       |
+
+You don't need to know all of these before contributing. Most changes only touch one or two of them at a time.
 
 ## Getting Started
 
+Follow the steps below to run the project on your own computer.
+
+Don't worry if you've never worked with a Next.js project before—each step is explained.
+
 ### Prerequisites
 
-- Node.js 18+
-- bun, npm, yarn, or pnpm
+Before you begin, make sure you have the following installed:
+
+- **Node.js 18 or later**
+- A package manager such as **npm**, **bun**, **pnpm**, or **yarn**
+- **Git**
+
+> **Note:** This guide uses **npm** for all examples. If you prefer **bun**, **pnpm**, or **yarn**, you can use the equivalent commands instead.
 
-### Setup
+You can verify your installation by running:
+
+```bash
+node -v
+npm -v
+git --version
+```
+
+### Step 1: Clone the repository
+
+Clone the project from GitHub:
+
+```bash
+git clone https://github.com/open-devhub/website.git
+```
+
+Move into the project directory:
 
 ```bash
-# Clone the repo
-git clone https://github.com/open-devhub/website
 cd website
+```
+
+### Step 2: Install dependencies
 
-# Install dependencies
+This project depends on several external packages. Install them using:
+
+```bash
 npm install
+```
+
+This may take a few minutes the first time.
+
+### Step 3: Start the development server
+
+Run:
 
-# Start the dev server
+```bash
 npm run dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) and you're in.
+The development server will start locally.
+
+Open your browser and visit:
+
+```
+http://localhost:3000
+```
+
+Whenever you save changes to the code, the browser automatically refreshes so you can instantly see your updates.
+
+### Step 4: Verify Everything Works
+
+Once the development server is running, open your browser and visit:
+
+```
+http://localhost:3000
+```
+
+You should see the DevHub homepage. Try navigating to a few pages to make sure everything loads correctly.
+
+If you've made changes, save your files and verify that the browser updates automatically.
 
 ## Project Structure
 
+Below is an overview of the repository structure to help you locate important files and folders.
+
 ```
 ├── 📁 .github
 │   └── 📁 workflows
@@ -140,52 +208,142 @@ Open [http://localhost:3000](http://localhost:3000) and you're in.
 │   ├── 📄 redirects.config.ts
 │   ├── 📄 staticdata.config.ts
 │   └── 📄 utils.ts
-├── 📄 .eslintrc.json
-├── 📄 .gitignore
-├── 📄 bun.lock
-├── 📄 components.json
-├── 📄 CONTRIBUTING.md
-├── 📄 LICENSE
-├── 📄 next.config.js
-├── 📄 package-lock.json
-├── 📄 package.json
-├── 📄 postcss.config.js
-├── 📄 README.md
-├── 📄 tailwind.config.ts
-├── 📄 tsconfig.json
-├── 📄 vercel.json
+├── app/                  → Pages of the site (Next.js App Router)
+│   ├── api/              → API routes (e.g. link previews)
+│   ├── pages/            → Renders the guide pages (Getting Started, FAQ, etc.)
+│   ├── articles/         → Article listing + individual article pages
+│   ├── partners/         → Partners page
+│   ├── resources/        → Resource library page
+│   └── rules/            → Community rules page
+├── components/           → Reusable React components
+│   ├── home/             → Landing page sections (Hero, Features, Stats, etc.)
+│   ├── site/             → Shared layout pieces (Navbar, Footer, Section)
+│   ├── ui/               → Generic building blocks (buttons, dialogs, badges…)
+│   └── bits/             → Visual/animation effects (glow, fuzzy text, cursor)
+├── content/              → Site copy and structured data
+│   ├── pages/            → Content for the guide pages
+│   ├── articles/         → Article content
+│   ├── resources.ts      → Resource library data
+│   └── rules.ts          → Community rules data
+├── lib/                  → Shared utility code
+│   ├── markdown/         → Markdown parser used for articles/pages
+│   ├── animations.ts     → Shared animation configs
+│   ├── colors.ts         → Color system used across the site
+│   └── utils.ts          → General helper functions
+└── hooks/                → Custom React hooks
 ```
 
 ## Contributing
 
-We welcome contributions of all kinds: bug fixes, new features, documentation improvements, and design feedback.
+We welcome contributions from developers of all experience levels, including first-time contributors!
+
+A typical contribution workflow looks like this:
+
+1. Fork this repository to your GitHub account.
+2. Clone your fork locally.
+3. Create a new branch.
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide. The short version:
+```bash
+git checkout -b feature/my-new-feature
+```
+
+4. Make your changes.
+5. Test your changes locally.
+6. Run the linter:
+
+```bash
+npm run lint
+```
+
+7. Commit your changes.
+
+```bash
+git commit -m "feat: add awesome feature"
+```
+
+8. Push your branch.
+
+```bash
+git push origin feature/my-new-feature
+```
+
+9. Open a Pull Request describing what you changed and why.
+
+New to open source? Look for issues tagged [`good first issue`](https://github.com/open-devhub/website/issues?q=is%3Aopen+label%3A%22good+first+issue%22). These are picked specifically to be approachable for first-time contributors.
+
+For a more detailed contribution guide, coding standards, and pull request expectations, please see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Useful Scripts
+
+| Command             | Description                            |
+| ------------------- | -------------------------------------- |
+| `npm run dev`       | Starts the local development server.   |
+| `npm run build`     | Creates an optimized production build. |
+| `npm run start`     | Runs the production build locally.     |
+| `npm run lint`      | Checks your code for linting issues.   |
+| `npm run typecheck` | Check for type errors.                 |
+| `npm run format`    | Formats the project using Prettier.    |
+
+## Testing Your Changes
+
+Before opening a Pull Request, make sure your changes work as expected.
+
+Run the linter:
 
-1. Fork the repo
-2. Create a branch (`git checkout -b feature/your-cool-feature`)
-3. Make your changes
-4. Run `npm run lint`
-5. Open a PR with a clear description
+```bash
+npm run lint
+```
+
+Then start the development server:
+
+```bash
+npm run dev
+```
+
+Open the website in your browser and verify that your changes appear correctly and don't introduce any issues.
+
+If the project adds automated tests in the future, be sure to run those as well before submitting your contribution.
+
+## Troubleshooting
+
+### `npm install` fails
 
-First time contributing to open source? Look for issues tagged [`good first issue`](https://github.com/open-devhub/website/issues?q=is%3Aopen+label%3A%22good+first+issue%22).
+Make sure you're using **Node.js 18 or later**.
 
-## Scripts
+### Port 3000 is already in use
+
+Run the development server on another port:
 
 ```bash
-npm run dev        # Start development server
-npm run build      # Production build
-npm run start      # Start production server
-npm run lint       # Run ESLint
-npm run format     # Run Prettier
+npm run dev -- -p 3001
+```
+
+### Module not found
+
+Delete the `node_modules` folder and reinstall dependencies:
+
+```bash
+rm -rf node_modules
+npm install
 ```
 
 ## Community
 
-- **Discord** - [devhub.vercel.app/join](https://devhub.vercel.app/join)
-- **GitHub Org** - [github.com/open-devhub](https://github.com/open-devhub)
-- **Email** - open-devhub@outlook.com
+Want to get involved? We'd love to have you!
+
+- **Website:** [devhub.vercel.app](https://devhub.vercel.app)
+- **Discord:** [Join DevHub](https://devhub.vercel.app/join) – Ask questions, connect with other developers, and stay up to date with the community.
+- **GitHub:** [open-devhub](https://github.com/open-devhub) – Explore our projects and contribute.
+- **Email:** open-devhub@outlook.com – Reach out for general inquiries or support.
 
 ## License
 
 Licensed under the GNU GPL v3.0 License. See the [LICENSE](./LICENSE) file for details.
+
+## Contributors
+
+Thanks to everyone who has contributed to this repository.
+
+<a href="https://github.com/open-devhub/website/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=open-devhub/website" />
+</a>