From 71065c93196a1021616b4ce7f3dd7ec78cadea34 Mon Sep 17 00:00:00 2001 From: sammy6378 Date: Wed, 3 Sep 2025 12:21:27 +0300 Subject: [PATCH 1/2] Enhance documentation structure and learning paths for clarity and progression --- Readme.md | 230 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 189 insertions(+), 41 deletions(-) diff --git a/Readme.md b/Readme.md index ef09c7f..044b385 100644 --- a/Readme.md +++ b/Readme.md @@ -33,21 +33,54 @@ Welcome to the **Modern JavaScript Documentation** – a comprehensive learning ## πŸ—ΊοΈ Documentation Structure +Our documentation is organized in a progressive learning path. **Follow the topics in order** for the best learning experience, as each section builds upon concepts from previous ones. + ``` πŸ“ docs/ -β”œβ”€β”€ πŸš€ getting-started.md # Start your journey here -β”œβ”€β”€ πŸ“„ intro.md # Project overview -β”œβ”€β”€ 🟨 js/ # JavaScript Documentation -β”‚ β”œβ”€β”€ basics.md # Variables, functions, objects -β”‚ └── advanced.md # Async/await, modules, patterns -β”œβ”€β”€ πŸ”· ts/ # TypeScript Documentation -β”‚ β”œβ”€β”€ intro.md # Getting started with TypeScript -β”‚ └── tips.md # Best practices and tips -└── πŸ“± react-native/ # React Native Documentation - β”œβ”€β”€ setup.md # Environment setup - └── components.md # Building components +β”œβ”€β”€ πŸš€ getting-started.md # Start your journey here +β”œβ”€β”€ πŸ“„ intro.md # Project overview +β”‚ +β”œβ”€β”€ 🟨 Javascript/ # JavaScript Documentation +β”‚ β”œβ”€β”€ πŸ“š Beginner/ # Foundation Concepts (Start Here) +β”‚ β”‚ β”œβ”€β”€ introduction-to-javascript.md # 1. What is JavaScript? +β”‚ β”‚ β”œβ”€β”€ variables.md # 2. Storing data +β”‚ β”‚ β”œβ”€β”€ arrays.md # 3. Working with lists +β”‚ β”‚ β”œβ”€β”€ functions.md # 4. Reusable code blocks +β”‚ β”‚ β”œβ”€β”€ objects.md # 5. Organizing data +β”‚ β”‚ └── projects.md # 6. Practice projects +β”‚ β”‚ +β”‚ └── πŸ”₯ Intermediate/ # Advanced Concepts (After Beginner) +β”‚ β”œβ”€β”€ advanced-functions.md # 7. Function mastery +β”‚ β”œβ”€β”€ dom-manipulation.md # 8. Web page interaction +β”‚ β”œβ”€β”€ es6-features.md # 9. Modern JavaScript +β”‚ β”œβ”€β”€ async-javascript/ # 10. Asynchronous Programming +β”‚ β”‚ β”œβ”€β”€ callbacks.md # 10a. Basic async +β”‚ β”‚ β”œβ”€β”€ promises.md # 10b. Promise patterns +β”‚ β”‚ β”œβ”€β”€ async-await.md # 10c. Modern async +β”‚ β”‚ └── asynchronous-operations.md # 10d. Complex operations +β”‚ β”œβ”€β”€ json-apis.md # 11. Working with APIs +β”‚ β”œβ”€β”€ error-handling.md # 12. Handling errors +β”‚ └── final-projects.md # 13. Capstone projects +β”‚ +β”œβ”€β”€ πŸ”· Typescript/ # TypeScript Documentation (After JS Intermediate) +β”‚ β”œβ”€β”€ intro.md # Getting started with TypeScript +β”‚ └── tips.md # Best practices and tips +β”‚ +└── πŸ“± react-native/ # React Native Documentation (After TypeScript) + β”œβ”€β”€ setup.md # Environment setup + └── components.md # Building components ``` +### πŸ“š **Learning Path Recommendations** + +> **🎯 Important**: Follow the numbered sequence above for optimal learning progression. Each topic introduces concepts that are essential for understanding subsequent materials. + +**Beginner Path**: `getting-started` β†’ `Javascript/Beginner` (1-6) β†’ Practice projects + +**Intermediate Path**: Complete Beginner β†’ `Javascript/Intermediate` (7-13) β†’ Build real applications + +**Advanced Path**: Complete Intermediate β†’ `Typescript` β†’ `React Native` β†’ Advanced projects + ## πŸš€ Quick Start for Contributors ### Prerequisites @@ -55,23 +88,34 @@ Welcome to the **Modern JavaScript Documentation** – a comprehensive learning - **Node.js** (v16 or higher) - **npm** or **yarn** - **Git** for version control +- **GitHub account** for contributing -### Setup Instructions +### 🍴 Fork & Setup Instructions -1. **Clone the repository** +1. **Fork the repository** + + Click the "Fork" button at the top right of the [repository page](https://github.com/sammy6378/reference) to create your own copy. + +2. **Clone your fork** ```bash - git clone https://github.com/sammy6378/reference.git + git clone https://github.com/YOUR_USERNAME/reference.git cd reference ``` -2. **Install dependencies** +3. **Add upstream remote** + + ```bash + git remote add upstream https://github.com/sammy6378/reference.git + ``` + +4. **Install dependencies** ```bash npm install ``` -3. **Start the development server** +5. **Start the development server** ```bash npm start @@ -79,73 +123,177 @@ Welcome to the **Modern JavaScript Documentation** – a comprehensive learning The site will be available at [http://localhost:3000](http://localhost:3000) -4. **Start contributing!** πŸŽ‰ +6. **Create a new branch for your changes** + + ```bash + git checkout -b feature/your-feature-name + ``` + +7. **Make your changes and test them locally** + +8. **Commit and push your changes** + + ```bash + git add . + git commit -m "Add: descriptive commit message" + git push origin feature/your-feature-name + ``` + +9. **Create a Pull Request** + + Go to your fork on GitHub and click "New Pull Request". Provide a clear description of your changes. ## πŸ“ How to Contribute -We welcome contributions from developers of all experience levels! Here's how you can help: +We welcome contributions from developers of all experience levels! Here are the ways you can help: + +### πŸ”„ **Contribution Workflow** + +1. **Fork** the repository to your GitHub account +2. **Clone** your fork locally +3. **Create a branch** for your specific changes +4. **Make your changes** following our guidelines +5. **Test** your changes locally +6. **Commit** with clear, descriptive messages +7. **Push** to your fork +8. **Submit a Pull Request** with detailed description ### πŸ› **Report Issues** -- Found a typo or error? [Open an issue](https://github.com/sammy6378/reference/issues) -- Suggestions for new content? We'd love to hear them! +- Found a typo, broken link, or error? [Open an issue](https://github.com/sammy6378/reference/issues) +- Use our issue templates for bug reports and feature requests +- Provide as much detail as possible to help us understand the problem -### ✍️ **Improve Documentation** +### ✍️ **Improve Existing Documentation** - Fix typos and improve clarity -- Add missing examples or explanations -- Translate content (coming soon) +- Update outdated examples or explanations +- Add missing code examples +- Improve existing tutorials ### πŸ†• **Add New Content** -- Write tutorials for new topics -- Create interactive examples -- Add best practices and tips +Before adding new content: -### 🎨 **Enhance Design** +- Check existing issues to see if it's already planned +- Open a discussion or issue to propose your idea +- Follow our content structure and style guidelines -- Improve the user interface -- Add new components +Types of content we're looking for: + +- New JavaScript concepts and features +- TypeScript tutorials and examples +- React Native components and patterns +- Best practices and coding standards +- Real-world project examples + +### 🎨 **Enhance Design & User Experience** + +- Improve the website's user interface +- Add new Docusaurus components - Optimize for mobile devices +- Enhance accessibility features ### πŸ“‹ **Content Guidelines** When contributing content, please follow these guidelines: -1. **Be Beginner-Friendly**: Assume readers are new to the topic -2. **Use Clear Examples**: Include practical, runnable code snippets -3. **Stay Current**: Focus on modern approaches and best practices -4. **Add Context**: Explain not just "how" but "why" -5. **Test Your Code**: Ensure all examples work as expected +1. **Be Beginner-Friendly**: + - Assume readers are new to the topic + - Define technical terms when first used + - Provide context and background information + +2. **Use Clear, Practical Examples**: + - Include runnable code snippets + - Show both correct and incorrect examples when helpful + - Use real-world scenarios + +3. **Stay Current**: + - Focus on modern approaches and best practices + - Use the latest stable versions of tools/frameworks + - Avoid deprecated methods unless explaining migration + +4. **Structure Content Well**: + - Use clear headings and subheadings + - Break up long sections with examples + - Include summary sections + +5. **Test Everything**: + - Ensure all code examples work as expected + - Test on different browsers/devices when relevant + - Verify all links are working ### πŸ“‚ **File Structure for New Content** +When creating new documentation files: + ```markdown --- sidebar_position: 1 title: Your Topic Title -description: Brief description of what this covers +description: Brief description for SEO and previews +tags: [javascript, beginner, tutorial] --- # Your Topic Title -Brief introduction explaining what the reader will learn. +Brief introduction explaining what the reader will learn and why it's important. ## Prerequisites + - What knowledge is assumed - Required tools or setup +- Links to prerequisite topics + +## Learning Objectives + +By the end of this tutorial, you will: +- Objective 1 +- Objective 2 +- Objective 3 ## Main Content -Your tutorial content with examples... + +Your tutorial content with practical examples... + +### Code Examples + +```javascript +// Always include comments explaining the code +const example = "Keep examples simple and focused"; +console.log(example); +``` + +## Practice Exercise + +Hands-on exercise for readers to test their understanding. ## Summary -Key takeaways and next steps -## Further Reading -- Links to related topics -- External resources +- Key takeaway 1 +- Key takeaway 2 +- Key takeaway 3 + +## Next Steps + +- What to learn next +- Related topics to explore + +## Additional Resources + +- [Link to official documentation](https://example.com) +- [Related tutorial](./related-topic.md) + ``` +### 🚫 **What NOT to Include** + +- Copyrighted content without permission +- Outdated or deprecated methods (unless explaining migration) +- Personal opinions presented as facts +- Content that doesn't add educational value +- Incomplete or untested code examples + ## πŸ› οΈ Development Commands | Command | Description | From 891253a5548fa21cc279d2d990c1abaf28430c10 Mon Sep 17 00:00:00 2001 From: sammy6378 Date: Wed, 3 Sep 2025 12:25:07 +0300 Subject: [PATCH 2/2] docs: Revise documentation structure for clarity and add branch naming conventions --- CONTRIBUTING.md | 157 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 146 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11f4563..deeaab5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,20 +52,42 @@ Before contributing, make sure you have: ### Documentation Structure -Our documentation is organized as follows: +Our documentation is organized in a progressive learning path. Follow the structure below when adding new content: ``` docs/ -β”œβ”€β”€ getting-started.md # Getting started guide -β”œβ”€β”€ js/ # JavaScript documentation -β”‚ β”œβ”€β”€ basics.md # JavaScript basics -β”‚ └── advanced.md # Advanced JavaScript -β”œβ”€β”€ ts/ # TypeScript documentation -β”‚ β”œβ”€β”€ intro.md # TypeScript introduction -β”‚ └── tips.md # TypeScript tips -└── react-native/ # React Native documentation - β”œβ”€β”€ setup.md # React Native setup - └── components.md # React Native components +β”œβ”€β”€ getting-started.md # Getting started guide +β”œβ”€β”€ intro.md # Project overview +β”‚ +β”œβ”€β”€ Javascript/ # JavaScript documentation +β”‚ β”œβ”€β”€ Beginner/ # Foundation concepts +β”‚ β”‚ β”œβ”€β”€ introduction-to-javascript.md # What is JavaScript? +β”‚ β”‚ β”œβ”€β”€ variables.md # Variables and data types +β”‚ β”‚ β”œβ”€β”€ arrays.md # Working with arrays +β”‚ β”‚ β”œβ”€β”€ functions.md # Functions and scope +β”‚ β”‚ β”œβ”€β”€ objects.md # Objects and methods +β”‚ β”‚ └── projects.md # Beginner projects +β”‚ β”‚ +β”‚ └── Intermediate/ # Advanced concepts +β”‚ β”œβ”€β”€ advanced-functions.md # Advanced function patterns +β”‚ β”œβ”€β”€ dom-manipulation.md # DOM interaction +β”‚ β”œβ”€β”€ es6-features.md # Modern JavaScript features +β”‚ β”œβ”€β”€ async-javascript/ # Asynchronous programming +β”‚ β”‚ β”œβ”€β”€ callbacks.md # Callback functions +β”‚ β”‚ β”œβ”€β”€ promises.md # Promise patterns +β”‚ β”‚ β”œβ”€β”€ async-await.md # Async/await syntax +β”‚ β”‚ └── asynchronous-operations.md # Complex async operations +β”‚ β”œβ”€β”€ json-apis.md # Working with APIs +β”‚ β”œβ”€β”€ error-handling.md # Error handling patterns +β”‚ └── final-projects.md # Intermediate projects +β”‚ +β”œβ”€β”€ Typescript/ # TypeScript documentation +β”‚ β”œβ”€β”€ intro.md # TypeScript introduction +β”‚ └── tips.md # TypeScript best practices +β”‚ +└── react-native/ # React Native documentation + β”œβ”€β”€ setup.md # Environment setup + └── components.md # Component development ``` ### Writing Guidelines @@ -151,17 +173,130 @@ Always use `map()` when you need to transform array elements. It's more function - Screenshots if you've made visual changes - References to any related issues +### Branch Naming Conventions + +To help with code reviews and project organization, please follow these branching guidelines: + +#### Branch Naming Format + +Use the following format for your branch names: + +``` +/ +``` + +#### Branch Types + +| Type | Purpose | Example | +| ---------- | -------------------------- | -------------------------------------- | +| `feat` | New features or content | `feat/add-async-await-tutorial` | +| `fix` | Bug fixes or corrections | `fix/broken-links-javascript-section` | +| `docs` | Documentation improvements | `docs/improve-contributing-guide` | +| `style` | Design/UI improvements | `style/enhance-mobile-navigation` | +| `refactor` | Code/content restructuring | `refactor/reorganize-beginner-content` | +| `test` | Adding or fixing tests | `test/add-code-example-validation` | +| `chore` | Maintenance tasks | `chore/update-dependencies` | + +#### Branch Naming Examples + +βœ… **Good Examples:** + +```bash +feat/typescript-generics-tutorial +fix/incorrect-array-examples +docs/update-installation-guide +style/improve-code-block-styling +refactor/split-large-javascript-file +``` + +❌ **Avoid:** + +```bash +my-changes +update +fix-stuff +new-feature +``` + +#### Creating and Working with Branches + +1. **Create a new branch** from main: + + ```bash + git checkout main + git pull upstream main # Sync with latest changes + git checkout -b feat/your-feature-name + ``` + +2. **Make your changes** and commit regularly: + + ```bash + git add . + git commit -m "Add: Clear description of what you added" + ``` + +3. **Push your branch** to your fork: + + ```bash + git push origin feat/your-feature-name + ``` + +4. **Create a Pull Request** with a clear title matching your branch purpose + +### Commit Message Guidelines + +Use clear, descriptive commit messages that follow this format: + +``` +: + +[Optional longer description] +``` + +**Examples:** + +```bash +feat: Add TypeScript interfaces tutorial +fix: Correct array method examples in beginner guide +docs: Update contribution guidelines with branch naming +style: Improve responsive design for mobile devices +``` + +**Types for commits:** + +- `feat:` New features or content +- `fix:` Bug fixes +- `docs:` Documentation changes +- `style:` Formatting, UI changes +- `refactor:` Code restructuring +- `test:` Adding tests +- `chore:` Maintenance + ### Pull Request Checklist Before submitting your pull request, make sure: +- [ ] Your branch name follows our naming conventions - [ ] The documentation builds without errors (`npm run build`) - [ ] All code examples are tested and work correctly - [ ] Links are working and point to the correct pages - [ ] Grammar and spelling are correct - [ ] The content follows our style guidelines +- [ ] Your commits have clear, descriptive messages +- [ ] You've synced with the latest main branch - [ ] You've added yourself to the contributors list (if applicable) +### Review Process + +To help us review your contribution quickly: + +1. **Use descriptive PR titles** that match your branch type +2. **Fill out the PR template** completely +3. **Reference related issues** using `#issue-number` +4. **Add screenshots** for visual changes +5. **Request specific reviewers** if you know who should review +6. **Respond to feedback** promptly and professionally + ## πŸ› Reporting Issues If you find bugs, typos, or have suggestions for improvement: