Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
171 lines (121 loc) · 6.37 KB

CONTRIBUTING.md

File metadata and controls

171 lines (121 loc) · 6.37 KB
Raw

Contributing to ShopSync Documentation and Landing Page

Thank you for your interest in contributing to the ShopSync documentation and landing page! This guide will help you understand how to contribute effectively.

About This Project

This repository hosts both the ShopSync documentation (built with Zensical and MkDocs compatibility) and the landing page (built with React and Vite). The landing page serves as the entry point for users to learn about ShopSync, explore its features, and access comprehensive documentation.

Project Structure

  • docs/ - Documentation source files
  • src/ - React landing page source code
    • components/ - Reusable React components (Navbar, Footer)
    • pages/ - Page components (Home, Features, About, Contact)
    • styles/ - CSS stylesheets
  • site/ - Built documentation (generated by Zensical)
  • public/ - Static assets for the landing page

How Can You Contribute?

There are many ways to contribute to our documentation and landing page:

Documentation Contributions

  • Fix typos and grammatical errors - Help us maintain professional, error-free documentation
  • Improve clarity - Rewrite confusing sections to make them easier to understand
  • Add examples - Provide code examples and use cases
  • Update outdated content - Help keep documentation current with the latest features
  • Create new content - Write new guides, tutorials, or reference materials
  • Improve organization - Suggest better ways to structure our documentation

Landing Page Contributions

  • UI/UX improvements - Enhance the design and user experience
  • Responsive design - Ensure the site works well on all devices
  • Performance optimizations - Improve loading times and performance
  • Accessibility - Make the site more accessible to all users
  • Content updates - Update feature descriptions and screenshots
  • Bug fixes - Fix any issues with navigation, styling, or functionality

Getting Started

For Documentation Changes

  1. Fork the repository - Create your own fork of the shopsync-landing repository
  2. Create a branch - Make your changes in a new branch with a descriptive name
  3. Make your changes - Edit or add documentation files in the docs/ directory
  4. Test locally - Run zensical serve to preview your changes
  5. Submit a pull request - Open a PR with a clear description of your changes

For Landing Page Changes

  1. Fork the repository - Create your own fork of the shopsync-landing repository
  2. Install dependencies - Run npm install or yarn install
  3. Create a branch - Make your changes in a new branch with a descriptive name
  4. Make your changes - Edit React components, styles, or pages in the src/ directory
  5. Test locally - Run npm run dev to start the development server
  6. Build and test - Run npm run build to ensure the build succeeds
  7. Submit a pull request - Open a PR with a clear description of your changes

Documentation Guidelines

Writing Style

  • Be clear and concise - Use simple language and short sentences
  • Be consistent - Follow the existing style and formatting conventions
  • Be accurate - Ensure all information is correct and up-to-date
  • Be inclusive - Use inclusive language and avoid assumptions about the reader

Formatting

  • Use Markdown formatting consistently
  • Include code blocks with appropriate syntax highlighting
  • Use headings to organize content hierarchically
  • Add links to related documentation where relevant
  • Include examples to illustrate concepts

Code Examples

When including code examples:

  • Ensure all code is tested and functional
  • Include comments to explain complex logic
  • Use realistic examples that demonstrate best practices
  • Specify the language for syntax highlighting

Example:

// Example: Initialize ShopSync client
const shopSync = new ShopSync({
  apiKey: "your-api-key",
  environment: "production",
});

Pull Request Process

  1. Update relevant documentation - Ensure your changes are complete
  2. Check for errors - Review your changes for typos and formatting issues
  3. Write a clear PR description - Explain what you changed and why
  4. Reference related issues - Link to any related issues or discussions
  5. Be responsive - Address feedback and questions from reviewers

PR Description Template

## Description
Brief description of your changes

## Type of Change
- [ ] Bug fix (fixing incorrect information)
- [ ] Enhancement (improving existing documentation)
- [ ] New content (adding new documentation)
- [ ] Other (please describe):

## Checklist
- [ ] I have reviewed my changes for accuracy
- [ ] I have checked for typos and grammatical errors
- [ ] I have followed the documentation style guide
- [ ] My changes are well-organized and easy to understand

Code of Conduct

Our Standards

  • Be respectful and inclusive in all interactions
  • Welcome newcomers and help them get started
  • Accept constructive criticism gracefully
  • Focus on what is best for the community
  • Show empathy towards other community members

Unacceptable Behavior

  • Harassment, discrimination, or offensive comments
  • Trolling or insulting/derogatory remarks
  • Personal or political attacks
  • Publishing others' private information without permission
  • Any conduct that could reasonably be considered inappropriate

Review Process

All contributions will be reviewed by maintainers. The review process ensures:

  • Accuracy - Information is correct and up-to-date
  • Clarity - Content is easy to understand
  • Completeness - All necessary information is included
  • Consistency - Changes align with existing documentation style

Reviewers may request changes or ask questions. Please be patient and responsive during the review process.

Questions or Need Help?

If you have questions about contributing:

  • Open an issue with the "question" label
  • Review existing issues and pull requests for examples
  • Reach out to maintainers for guidance

Recognition

We value all contributions! Contributors will be recognized for their efforts in helping improve the ShopSync documentation.

License

By contributing to this documentation, you agree that your contributions will be licensed under the GNU GPL v3.0 License, consistent with the project's existing license.

Thank you for helping make ShopSync documentation better for everyone!