Skip to main content

Contributing Guide

Thank you for your interest in contributing to the Refract documentation! This project is part of the Technical Writers Mentorship Program (TWMP) and serves as a capstone project to practice documentation best practices for a fictional JavaScript UI framework.

We're Here to Help!

This is a learning project, so we welcome contributions from writers of all experience levels. Don't hesitate to ask questions or seek guidance!

How Can You Contribute?​

There are several ways to contribute to this documentation project:

Improving Content​

  • Fix typos, grammatical errors, or unclear explanations
  • Add missing code examples or improve existing ones
  • Enhance the organization and flow of content
  • Add practical examples and use cases
  • Improve consistency in tone and style

Reporting Issues​

Found something that doesn't seem right? Please let us know by:

  • Creating an issue on GitHub
  • Providing clear descriptions of what needs improvement
  • Suggesting specific changes or alternatives

Suggesting New Content​

Have ideas for new tutorials, guides, or explanations? We'd love to hear them! Consider suggesting:

  • New tutorial topics that would help learners
  • Additional examples for complex concepts
  • Better ways to explain challenging topics

Documentation Structure​

Our documentation follows a specific organization to help users find what they need:

  • Getting Started: Basic introductions and setup guides
  • Core Concepts: Fundamental Refract concepts like refractions and optics
  • Tutorials: Step-by-step building guides
  • API Reference: Detailed API documentation
  • Advanced Guides: Complex topics and optimization techniques
info

When adding new content, please place it in the appropriate section to maintain our information architecture.

Making Contributions​

Development Setup​

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/your-username/Refract.git
    cd Refract
  3. Install dependencies: 
    npm install
  4. Run the development server: 
    npm start

Writing Guidelines​

  • Use clear, simple language that's accessible to beginners

  • Include code examples for all major concepts

  • Follow existing patterns and formatting conventions

  • Use descriptive headings that clearly indicate the content

  • Add internal links to related content when appropriate

Submission Process​

  1. Create a new branch for your changes:

    git checkout -b docs/your-feature-name

  2. Make your changes following our writing guidelines

  3. Test your changes by running the development server:

    npm start

  4. Commit your changes with descriptive messages:

    git add .
    git commit -m "commit mesage"
    git push origin docs/your-feature-name

  5. Push to your fork and open a pull request

Content Standards​

  • We strive to maintain high-quality documentation that:

  • Explains concepts clearly with practical examples

  • Uses consistent terminology throughout

  • Provides value to developers learning Refract

  • Follows technical writing best practices

  • Maintains a professional yet approachable tone

important

All contributions should maintain or improve the quality of our documentation. This includes proper formatting, accurate information, and clear explanations.

Code of Conduct​

By participating in the Refract community, you agree to abide by our Code of Conduct. We're committed to providing a friendly, safe, and welcoming environment for everyone.

Recognition​

We appreciate all contributions! While this is a learning project, we recognize contributors through:

  • Credit in commit history and pull requests
  • Learning experience and portfolio building
  • The satisfaction of helping other learners

Getting Help​

If you need assistance or have questions:

  • Open an issue on GitHub
  • Review existing documentation for guidance
  • Check the FAQ for common questions
All Experience Levels Are Welcomed!

This project is designed for learning and practice. Don't worry if you're new to technical writing—we welcome contributors at all levels!

License​

By contributing to this project, you agree that your contributions will be licensed under the same Apache 2.0 License that covers the project.

Thank you for considering contributing to the Refract documentation! Your help makes this learning project better for everyone involved in the Technical Writers Mentorship Program.

The Refract Documentation Team