# Contributing to UX Writing Skill

Thanks for your interest in improving this skill! Contributions are welcome and appreciated.

## Ways to Contribute

### 1. Report Issues
- Found a typo or error? Open an issue
- Unclear instructions? Let us know
- Missing a common pattern? Suggest it

### 2. Share Examples
- Real-world before/after improvements
- Industry-specific patterns (healthcare, fintech, etc.)
- Unique voice applications
- Edge cases or tricky scenarios

### 3. Add Templates
- New UI patterns (e.g., chat interfaces, voice assistants)
- Specialized content types (legal, medical, technical)
- Workflow templates
- Evaluation frameworks

### 4. Improve Documentation
- Clarify existing instructions
- Add more examples to patterns
- Translate to other languages
- Update outdated references

### 5. Extend Reference Materials
- Accessibility guidelines
- Localization best practices
- Industry-specific standards
- Research citations

## For Non-Technical Contributors

**New to GitHub?** No problem! You don't need to be a developer to contribute. Here are simple ways to share your expertise:

### Option 1: Open an Issue

1. **Go to the repository** on GitHub
2. **Click the "Issues" tab** at the top
3. **Click the green "New issue" button**
4. **Describe your contribution**:
   - Paste your suggested text or example
   - Explain what it improves or adds
   - Include any context that's helpful
5. **Click "Submit new issue"**

That's it! A maintainer will review and incorporate your contribution.

### Option 2: Edit Files Directly on GitHub

You can edit files right in your browser without installing anything:

1. **Navigate to the file you want to edit** (like `examples/real-world-improvements.md`)
2. **Click the pencil icon** (✏️) in the top right corner
3. **Make your changes** in the editor
4. **Scroll down** to the "Propose changes" section
5. **Write a brief description** of what you changed
6. **Click "Propose changes"** (green button)
7. **Click "Create pull request"** on the next screen

GitHub will handle the technical parts automatically. A maintainer will review your changes and merge them.

### Option 3: Send It Directly

If GitHub feels overwhelming, you can:

- **Email your contribution** to the maintainer (see README for contact)
- **Share a Google Doc** with your suggested additions
- **Post in community channels** where this skill is discussed

Someone will help get your contribution into the repository.

### What Makes a Good Contribution?

Whether you're submitting an issue or editing directly:

- **Be specific**: Instead of "add more examples," share the actual example
- **Explain the value**: Why is this helpful? What problem does it solve?
- **Keep it realistic**: Use examples from actual products when possible
- **Follow the existing format**: Look at similar content and match the style

### Don't Worry About Perfection

Submit your idea even if:
- You're not sure about the formatting
- Your example isn't polished yet
- You're uncertain if it fits

Maintainers can help refine it. The hard part is having the expertise — you have that!

### Need Help?

Stuck on something? Open an issue with the title "Help: [what you need]" and describe where you're stuck. The community is here to help.

## Contribution Guidelines

### Content Standards

All contributions should follow these principles:

1. **Evidence-based**: Based on established UX writing best practices or user research
2. **Actionable**: Provides clear, practical guidance
3. **Concise**: Respects the reader's time
4. **Well-structured**: Easy to scan and reference
5. **Example-rich**: Shows, doesn't just tell

### Style Guidelines

- Use sentence case for headings
- Use em dashes (—) not hyphens (-) for breaks
- Keep examples realistic and specific
- Include both "do" and "don't" examples where helpful
- Score examples against the four quality standards when relevant

### File Organization

```
ux-writing/
├── SKILL.md (core principles and patterns)
├── README.md (GitHub documentation)
├── references/ (supporting materials)
│   ├── voice-chart-template.md
│   ├── content-usability-checklist.md
│   └── patterns-detailed.md
├── examples/ (real-world applications)
│   └── real-world-improvements.md
└── templates/ (fillable guides)
    ├── error-message-template.md
    ├── empty-state-template.md
    └── onboarding-flow-template.md
```

### Adding New Content

**New examples** go in `examples/`
- Show before/after with scoring
- Explain why the improvement works
- Keep consistent with existing format

**New templates** go in `templates/`
- Provide clear structure and guidance
- Include checklist for verification
- Show filled examples

**New reference materials** go in `references/`
- Comprehensive coverage of topic
- Links to authoritative sources
- Maintains consistent voice

### Submitting Changes

1. **Fork the repository**
2. **Create a feature branch** (`git checkout -b add-chat-pattern`)
3. **Make your changes** following the guidelines above
4. **Test the skill** — verify Claude can use your additions effectively
5. **Update CHANGELOG.md** with your changes under "Unreleased"
6. **Submit a pull request** with clear description of what and why

### Pull Request Template

```markdown
## What does this PR do?
[Brief description of changes]

## Why is this needed?
[Explain the problem this solves or value it adds]

## What type of contribution is this?
- [ ] Bug fix
- [ ] New example
- [ ] New template
- [ ] New reference material
- [ ] Documentation improvement
- [ ] Other (please describe)

## Have you:
- [ ] Tested the skill with your changes?
- [ ] Followed the style guidelines?
- [ ] Updated CHANGELOG.md?
- [ ] Added examples where applicable?

## Additional context
[Any other relevant information]
```

## Code of Conduct

### Our Standards

- **Respectful**: Treat all contributors with respect
- **Constructive**: Provide helpful, actionable feedback
- **Inclusive**: Welcome contributions from all backgrounds
- **Patient**: Remember everyone is learning

### Unacceptable Behavior

- Harassment or discrimination
- Unconstructive criticism
- Spam or promotional content
- Sharing private information

## Questions?

Not sure if your idea fits? Open an issue to discuss before investing time in a full PR.

## Recognition

Contributors will be acknowledged in:
- CHANGELOG.md for specific contributions
- README.md for significant additions
- Special recognition for ongoing contributors

## License

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

---

Thank you for helping make UX writing more systematic and accessible! 🎉