[Docs] Improve README with setup instructions for new contributors #112

[sarika-03]

Description

This PR improves the README with comprehensive setup and installation instructions for new contributors. The current README lacks clear guidance on how to get started, making it difficult for first-time contributors to set up and run the project locally.

**Fixes #112 **

Changes

Added Sections:

1. 🚀 Getting Started

• Prerequisites section with version requirements (Node.js v16+, npm v8+, Git)
• Step-by-step installation guide with correct directory navigation (cd site)
• Clear instructions: clone → navigate to site/ → install → run
• Local development server information (http://localhost:8000)

2. 📂 Project Structure

• Visual folder tree showing repository organization
• Highlights key directories (site/src/components/ShapeBuilder/)
• Clear indication of where beginners should start

3. 🛠️ Available Scripts

• Table format listing all npm commands with descriptions
• npm start - Start development server
• npm run build - Production build
• npm run lint - Code quality checks
• npm run clean - Clear Gatsby cache
• npm run serve - Serve production build

4. 🐛 Troubleshooting

• Port 8000 already in use - Solution provided
• Gatsby cache issues - npm run clean steps
• Node version mismatches - nvm instructions
• Common error resolution guides

5. 💡 Enhanced Usage Instructions

• Step-by-step guide to create custom polygon shapes
• Keyboard shortcuts table (Ctrl+Click, Ctrl+Z, Enter, Double-click)
• Clear explanation of coordinate export process
• Visual examples with generated coordinates

6. 🤝 Improved Contributing Section

• Complete fork → clone → branch → commit → push → PR workflow
• Commit message format with concrete examples
• Sign-off requirements clearly explained (git commit -s)
• Branch naming conventions
• Step-by-step instructions for first-time contributors

Improvements Made:

[X]Added emoji icons for better visual navigation
[X]Organized content with clear hierarchical headings
[X]Included code blocks for copy-paste convenience
[X]Added troubleshooting section for common issues
[X]Enhanced contribution workflow documentation
[X]Maintained existing community and license sections
[X]Professional formatting throughout

Root Cause

New contributors frequently struggle with:

1. Not knowing package.json is in site/ folder, not root
2. Running npm install in wrong directory
3. Lack of troubleshooting guidance for common setup issues
4. Unclear contribution workflow

Solution

Comprehensive documentation that:

• Guides contributors through every step of setup
• Provides troubleshooting for common issues
• Follows CNCF project documentation best practices
• Makes the repository more welcoming to newcomers

Testing

• Verified all command examples work correctly
• Tested setup process from scratch in clean environment
• Confirmed all links are valid and accessible
• Checked formatting renders correctly on GitHub
• Validated code blocks and syntax highlighting
• Ensured compatibility with existing documentation structure

Screenshots

Before

Missing Setup Instructions:

Current README lacks setup, troubleshooting, and clear contribution guidelines

After

Comprehensive Getting Started Section:

New README includes step-by-step setup, project structure, scripts, troubleshooting, and contribution workflow

Example: New Getting Started Section

Example: Project Structure Section

Example: Troubleshooting Section

Impact

Benefits for Contributors:

• ⚡ Faster onboarding - Contributors can start in minutes instead of hours
• 🎯 Reduced confusion - Clear path from clone to first contribution
• 🐛 Self-service debugging - Troubleshooting guide reduces support requests
• 📚 Better documentation - Aligns with CNCF documentation standards
• 🤝 Improved experience - Makes repository more welcoming

Benefits for Maintainers:

• 📉 Fewer setup questions in Slack/forums
• ✅ Higher quality contributions from better-informed contributors
• ⏱️ Less time spent on repetitive setup help
• 🌟 More professional project presentation

Additional Context

This improvement addresses common pain points observed in:

• New contributor onboarding sessions
• Slack channel setup questions
• GitHub issue comments asking "how to run this?"

The enhanced documentation follows patterns from successful CNCF projects and makes shape-builder more accessible to the global open-source community.

---

Notes for Reviewers

• This PR fixes [Docs] Improve README with setup instructions for new contributors #112
• All existing content preserved, only additions made
• No code changes, documentation only
• Tested rendering on GitHub preview

[Signed commits](https://github.com/meshery/meshery/blob/master/CONTRIBUTING.md#signing-off-on-commits-developer-certificate-of-origin)

• Yes, I signed my commits.

[kishore08-07]

@sarika-03
Thank you for your contribution!
Let's discuss this during the website call today at 6:30 PM IST | 8 AM CT
Add it as an agenda item to the meeting minutes, if you would :)

[sarika-03]

@saurabhraghuvanshii Do you want any changes ?

[saurabhraghuvanshii]

@sarika-03 Also add make commands guide