From 707e28c22193dbf20b4d87e16d2e6ca2400fada1 Mon Sep 17 00:00:00 2001 From: Afolami Anuoluwapo <161776085+aabxtract@users.noreply.github.com> Date: Fri, 16 Jan 2026 23:50:10 +0100 Subject: [PATCH] Create navigation guide for new contributors Added a comprehensive navigation guide for new contributors to the Base documentation, covering key topics, contribution pathways, and community resources. --- NAVIGATION.md | 522 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 522 insertions(+) create mode 100644 NAVIGATION.md diff --git a/NAVIGATION.md b/NAVIGATION.md new file mode 100644 index 00000000..db1592e5 --- /dev/null +++ b/NAVIGATION.md @@ -0,0 +1,522 @@ +# Base Documentation Navigation Guide for New Contributors + +Welcome to the Base ecosystem! This guide will help you navigate the Base documentation repository and start contributing, regardless of your experience level. + +--- + +## 📚 Table of Contents + +1. [What is Base?](#what-is-base) +2. [Understanding the Documentation Repository](#understanding-the-documentation-repository) +3. [Getting Started - For All Levels](#getting-started---for-all-levels) +4. [Contribution Pathways by Skill Level](#contribution-pathways-by-skill-level) +5. [Repository Structure](#repository-structure) +6. [How to Contribute](#how-to-contribute) +7. [Resources & Support](#resources--support) +8. [Community Guidelines](#community-guidelines) + +--- + +## 🌐 What is Base? + +Base is an Ethereum Layer 2 (L2) blockchain built on the OP Stack in collaboration with Optimism and incubated by Coinbase. It offers: + +- **Secure & Low-Cost**: Transactions at a fraction of Ethereum mainnet costs +- **EVM Compatible**: Deploy existing Ethereum smart contracts without modification +- **Developer-Friendly**: Comprehensive tooling and documentation +- **No Native Token**: Uses ETH for gas, simplifying the user experience + +**Key Use Cases**: DeFi, NFTs, gaming, social dApps, payments, and cross-chain bridges. + +--- + +## 📖 Understanding the Documentation Repository + +The Base documentation lives at [github.com/base/docs](https://github.com/base/docs) and is written primarily in TypeScript and MDX (Markdown + JSX). + +**Live Documentation**: [docs.base.org](https://docs.base.org) + +**Repository Stats** (as of January 2026): +- Language: TypeScript +- Active development with regular updates +- Open to community contributions + +--- + +## 🎯 Getting Started - For All Levels + +### Prerequisites + +Before contributing, you'll need: + +1. **GitHub Account**: [Sign up here](https://github.com/signup) if you don't have one +2. **Git Installed**: [Download Git](https://git-scm.com/downloads) +3. **Code Editor**: We recommend [VS Code](https://code.visualstudio.com/) +4. **Node.js**: [Install Node.js](https://nodejs.org/) (LTS version recommended) + +### First Steps + +1. **Explore the Live Documentation** + - Visit [docs.base.org](https://docs.base.org) + - Navigate through different sections to understand the content structure + - Identify areas that could be improved or gaps in documentation + +2. **Read the Repository README** + - Go to [github.com/base/docs](https://github.com/base/docs) + - Read the README.md file thoroughly + - Check for CONTRIBUTING.md for specific contribution guidelines + +3. **Join the Community** + - Discord: [Join Base Discord](https://discord.com/invite/buildonbase) + - GitHub Discussions: Check the Issues and Discussions tabs + - Follow [@base](https://x.com/base) on X (Twitter) + +--- + +## 🎓 Contribution Pathways by Skill Level + +### 🟢 Beginner Level (New to Open Source or Web3) + +**What You Can Contribute:** + +1. **Fix Typos & Grammar** + - Look for spelling mistakes, grammatical errors, or unclear sentences + - These are labeled as "good first issue" in many repositories + - Example: Fixing "teh" → "the" or clarifying confusing sentences + +2. **Improve Existing Documentation** + - Add missing commas, improve sentence structure + - Break long paragraphs into shorter, more readable sections + - Add line breaks or formatting to improve readability + +3. **Report Issues** + - Found something confusing? Open an issue! + - Describe what's unclear and suggest improvements + - Use the Issues tab on GitHub + +4. **Update Outdated Links** + - Check if external links still work + - Update deprecated URLs + - Verify that internal navigation links are correct + +**Learning Resources for Beginners:** +- [Git & GitHub Tutorial](https://docs.github.com/en/get-started/quickstart/hello-world) +- [Markdown Guide](https://www.markdownguide.org/) +- [First Contributions](https://github.com/firstcontributions/first-contributions) + +--- + +### 🟡 Intermediate Level (Some Development Experience) + +**What You Can Contribute:** + +1. **Write New Tutorial Sections** + - Create step-by-step guides for common tasks + - Add code examples with explanations + - Write "How-To" guides for specific use cases + +2. **Improve Code Examples** + - Review existing code snippets for accuracy + - Add comments to explain complex code + - Update examples to use latest best practices + +3. **Add Missing Documentation** + - Identify features that lack documentation + - Write comprehensive guides for undocumented tools + - Create comparison tables for different approaches + +4. **Translate Documentation** + - Help make Base accessible to non-English speakers + - Translate key sections into other languages + - Maintain consistency in translated content + +5. **Enhance Navigation** + - Improve table of contents + - Add internal linking between related topics + - Create visual diagrams or flowcharts + +**Skills to Develop:** +- TypeScript basics +- React fundamentals (for MDX files) +- Web3 concepts +- Technical writing + +**Recommended Reading:** +- [Base Developer Documentation](https://docs.base.org) +- [TypeScript Handbook](https://www.typescriptlang.org/docs/) +- [Technical Writing Guide](https://developers.google.com/tech-writing) + +--- + +### 🔴 Advanced Level (Experienced Developers) + +**What You Can Contribute:** + +1. **Build Interactive Examples** + - Create live code playgrounds + - Build interactive tutorials using React components + - Develop visual demonstrations of concepts + +2. **Architecture Documentation** + - Write technical deep-dives on Base architecture + - Document internal systems and protocols + - Create sequence diagrams and system designs + +3. **API Reference Updates** + - Document new API endpoints + - Write comprehensive SDK documentation + - Add TypeScript type definitions + +4. **Performance & Optimization** + - Improve documentation site performance + - Optimize build processes + - Implement better search functionality + +5. **Integration Guides** + - Write guides for integrating Base with other tools + - Document best practices for production deployments + - Create security hardening guides + +6. **Review Pull Requests** + - Help review other contributors' work + - Provide constructive feedback + - Test changes locally before approval + +**Advanced Skills:** +- Deep TypeScript/JavaScript knowledge +- React and modern web frameworks +- Blockchain/Web3 development +- DevOps and CI/CD +- Documentation frameworks (like Docusaurus, Nextra, or Mintlify) + +**Advanced Resources:** +- [OP Stack Documentation](https://docs.optimism.io/) +- [Ethereum Development Documentation](https://ethereum.org/en/developers/docs/) +- [Base GitHub Organization](https://github.com/base) + +--- + +## 🗂️ Repository Structure + +Understanding the repository structure helps you navigate and contribute effectively: + +``` +base/docs/ +├── docs/ # Main documentation content +│ ├── get-started/ # Getting started guides +│ ├── base-chain/ # Base blockchain documentation +│ ├── base-account/ # Account-related docs +│ ├── mini-apps/ # Mini apps documentation +│ ├── onchainkit/ # OnchainKit guides +│ └── cookbook/ # Code recipes and examples +├── src/ # Source code for doc site +├── public/ # Static assets (images, etc.) +├── package.json # Dependencies +├── README.md # Repository overview +└── CONTRIBUTING.md # Contribution guidelines (if exists) +``` + +**Key Directories:** + +- **`/docs`**: All Markdown/MDX documentation files +- **`/src`**: React components and site configuration +- **`/public`**: Images, icons, and static files + +--- + +## 🤝 How to Contribute + +### Step 1: Fork the Repository + +1. Go to [github.com/base/docs](https://github.com/base/docs) +2. Click the "Fork" button in the top-right corner +3. This creates a copy in your GitHub account + +### Step 2: Clone Your Fork + +```bash +# Clone your forked repository +git clone https://github.com/YOUR-USERNAME/docs.git + +# Navigate into the directory +cd docs + +# Add the original repository as 'upstream' +git remote add upstream https://github.com/base/docs.git +``` + +### Step 3: Set Up Your Development Environment + +```bash +# Install dependencies +npm install +# or +yarn install + +# Start the development server +npm run dev +# or +yarn dev +``` + +The documentation site should now be running at `http://localhost:3000` + +### Step 4: Create a New Branch + +```bash +# Create and switch to a new branch +git checkout -b fix/improve-getting-started-guide + +# Branch naming conventions: +# - fix/description (for bug fixes) +# - docs/description (for documentation changes) +# - feat/description (for new features) +``` + +### Step 5: Make Your Changes + +1. Edit the relevant files in your code editor +2. Test your changes locally in the browser +3. Ensure all links work and formatting is correct +4. Check for typos and clarity + +### Step 6: Commit Your Changes + +```bash +# Stage your changes +git add . + +# Commit with a clear message +git commit -m "docs: improve getting started guide clarity + +- Fixed typos in installation section +- Added missing step for environment setup +- Clarified npm vs yarn usage" +``` + +**Good Commit Message Format:** +``` +type: short description (50 chars or less) + +- Bullet point explanation +- Another detail if needed +``` + +**Types**: `docs`, `fix`, `feat`, `refactor`, `test`, `chore` + +### Step 7: Push to Your Fork + +```bash +# Push your branch to your fork +git push origin fix/improve-getting-started-guide +``` + +### Step 8: Create a Pull Request + +1. Go to your fork on GitHub +2. Click "Compare & pull request" +3. Fill out the PR template: + - **Title**: Clear, concise description + - **Description**: Explain what you changed and why + - **Related Issue**: Link to any related issues +4. Click "Create pull request" + +### Step 9: Respond to Feedback + +- Maintainers may request changes +- Make requested updates in your branch +- Push changes to the same branch (PR updates automatically) +- Be patient and respectful in discussions + +### Step 10: Celebrate! 🎉 + +Once merged, your contribution is live! You're now an official Base contributor. + +--- + +## 📌 Best Practices + +### Documentation Writing + +1. **Be Clear and Concise** + - Use simple language + - Avoid jargon unless necessary + - Define technical terms + +2. **Use Active Voice** + - ✅ "Click the button to deploy" + - ❌ "The button should be clicked to deploy" + +3. **Include Code Examples** + - Show, don't just tell + - Add comments to explain complex parts + - Test all code before submitting + +4. **Structure Content Well** + - Use headers to organize sections + - Add bullet points for lists + - Include a table of contents for long pages + +5. **Link Related Content** + - Reference other relevant docs + - Link to external resources + - Provide context for next steps + +### Code Contributions + +1. **Follow the Style Guide** + - Match existing code formatting + - Use consistent naming conventions + - Follow TypeScript best practices + +2. **Test Thoroughly** + - Run the site locally + - Check all links + - Test on different screen sizes + +3. **Keep PRs Focused** + - One logical change per PR + - Avoid mixing unrelated changes + - Make reviewing easier for maintainers + +--- + +## 🆘 Resources & Support + +### Official Resources + +- **Documentation**: [docs.base.org](https://docs.base.org) +- **Base Website**: [base.org](https://base.org) +- **Developer Portal**: [base.dev](https://base.dev) +- **GitHub**: [github.com/base](https://github.com/base) +- **Blog**: [blog.base.dev](https://blog.base.dev) + +### Community + +- **Discord**: [discord.com/invite/buildonbase](https://discord.com/invite/buildonbase) +- **X (Twitter)**: [@base](https://x.com/base) +- **Reddit**: [r/BASE](https://www.reddit.com/r/BASE/) +- **LinkedIn**: [linkedin.com/company/coinbase](https://linkedin.com/company/coinbase) + +### Learning Resources + +- **Base Documentation**: Start here for all Base-specific info +- **Optimism Docs**: [docs.optimism.io](https://docs.optimism.io) - Base uses OP Stack +- **Ethereum Docs**: [ethereum.org/developers](https://ethereum.org/en/developers/) +- **Web3 University**: Free courses on blockchain development + +### Getting Help + +1. **Check Existing Issues**: Someone may have asked the same question +2. **Discord**: Ask in the #documentation or #support channels +3. **GitHub Discussions**: Start a discussion for broader questions +4. **Create an Issue**: For bugs or specific problems + +--- + +## 🌟 Community Guidelines + +### Code of Conduct + +Base follows an open and inclusive code of conduct: + +1. **Be Respectful** + - Treat everyone with respect and kindness + - Welcome newcomers warmly + - Assume good intentions + +2. **Be Constructive** + - Provide helpful feedback + - Focus on the idea, not the person + - Offer solutions, not just criticism + +3. **Be Collaborative** + - Work together towards common goals + - Share knowledge freely + - Help others learn and grow + +4. **Be Professional** + - Avoid offensive language + - Stay on topic + - Respect privacy and boundaries + +### Reporting Issues + +If you encounter harassment or violations of the code of conduct: +- Contact the Base team via Discord +- Report through GitHub's reporting features +- Email support if available + +--- + +## 🎁 Additional Opportunities + +### Beyond Documentation + +1. **Base Grants Program** + - Build projects on Base + - [Apply for funding](https://paragraph.com/@grants.base.eth/calling-based-builders) + +2. **Base Mentorship Program** + - Get paired with experienced Base developers + - [Learn more](https://docs.base.org/get-started/base-mentorship-program) + +3. **Builder Rewards** + - Earn rewards for building on Base + - [BuildersScore](https://www.builderscore.xyz/) + +4. **Retroactive Funding** + - Get funded for past contributions + - [Optimism RetroPGF](https://atlas.optimism.io/) + +--- + +## 🏁 Next Steps + +Ready to start contributing? Here's your action plan: + +### For Complete Beginners: +1. ✅ Read this guide thoroughly +2. ✅ Create a GitHub account +3. ✅ Star and fork the base/docs repository +4. ✅ Join the Base Discord +5. ✅ Find a "good first issue" label +6. ✅ Make your first contribution! + +### For Intermediate Contributors: +1. ✅ Review the Base documentation +2. ✅ Identify gaps or improvements +3. ✅ Open an issue to discuss your idea +4. ✅ Create a detailed PR with your changes +5. ✅ Help review others' PRs + +### For Advanced Contributors: +1. ✅ Explore the codebase architecture +2. ✅ Propose major improvements or new features +3. ✅ Become a regular reviewer +4. ✅ Mentor new contributors +5. ✅ Lead documentation initiatives + +--- + +## 📞 Contact & Links + +- **Repository**: [github.com/base/docs](https://github.com/base/docs) +- **Issue Tracker**: [github.com/base/docs/issues](https://github.com/base/docs/issues) +- **Suggest Edits**: Look for "Suggest edits" links on docs pages +- **Raise Issues**: Use "Raise issue" links on specific pages + +--- + +## 🙏 Thank You! + +Thank you for your interest in contributing to Base! Every contribution, no matter how small, helps make Base more accessible and useful for developers worldwide. Your work helps bring the world onchain. 🌍→⛓️ + +**Remember**: Everyone was a beginner once. Don't be afraid to ask questions, make mistakes, and learn. The Base community is here to support you! + +Happy contributing! 🚀✨ + +--- + +*Last Updated: January 2026* +*For the most current information, always refer to the official Base documentation and GitHub repository.*