Skip to main content

Contributing to Documentation

Thank you for your interest in contributing to the Solverhood Developer Hub! This guide will help you understand how to contribute effectively and maintain the quality of our documentation.

🤝 How to Contribute​

1. Quick Edits​

The easiest way to contribute is through the "Edit this page" links on any documentation page:

  1. Navigate to the page you want to edit
  2. Click the "Edit this page" link in the top-right corner
  3. Make your changes in the GitHub editor
  4. Submit a pull request with a clear description

2. Adding New Content​

For new documentation pages:

  1. Create a new Markdown file in the appropriate directory
  2. Follow the Content Guidelines below
  3. Update the sidebar configuration if needed
  4. Submit a pull request

3. Reporting Issues​

If you find problems with the documentation:

  1. Create a GitHub issue with the "documentation" label
  2. Describe the problem clearly
  3. Include steps to reproduce if applicable
  4. Suggest improvements if you have ideas

📝 Content Guidelines​

Writing Style​

Tone and Voice​

  • Professional but friendly: Write as if you're explaining to a colleague
  • Clear and concise: Avoid unnecessary jargon and complex sentences
  • Action-oriented: Use active voice and imperative mood for instructions
  • Inclusive: Use inclusive language and consider diverse audiences

Structure​

# Page Title

Brief description of what this page covers.

## Section Heading

Content for this section.

### Subsection Heading

More detailed content.

## Code Examples

```go
// Always include comments in code examples
func example() {
    // This is a good example
}
```

Next Steps​

Links to related content or next steps.


### Markdown Best Practices

#### Headers
```markdown
# Main page title (H1)
## Section heading (H2)
### Subsection heading (H3)
#### Minor heading (H4)

Code Blocks​

# For inline code

Use `backticks` for inline code.

# For code blocks

```go
func example() {
    return "Hello, World!"
}
```

For syntax highlighting

interface User {
  id: string;
  name: string;
}

#### Links
```markdown
# Internal links
[Link text](/docs/path/to/page)

# External links
[Link text](https://example.com)

# Links with descriptions
[Link text](https://example.com "Description")

Lists​

# Unordered lists

- Item 1
- Item 2
  - Sub-item 2.1
  - Sub-item 2.2

# Ordered lists

1. First step
2. Second step
3. Third step

# Task lists

- [x] Completed task
- [ ] Pending task

Front Matter​

Every documentation page should include front matter:

---
sidebar_position: 1
description: Brief description of the page content
---

Front Matter Options​

  • sidebar_position: Order in the sidebar (lower numbers appear first)
  • description: Brief description for search and SEO
  • title: Custom page title (optional)
  • keywords: Search keywords (optional)

🏗️ Project Structure​

Directory Organization​

docs/
├── intro.md                    # Homepage
├── getting-started.md          # Setup guide
├── architecture/               # Architecture documentation
│   ├── overview.md
│   ├── components.md
│   └── patterns.md
├── frontend/                   # Frontend guides
│   ├── guide.md
│   ├── components.md
│   └── state-management.md
├── backend/                    # Backend guides
│   ├── overview.md
│   ├── setup.md
│   └── patterns.md
├── api/                        # API documentation
│   ├── overview.md
│   ├── authentication.md
│   └── endpoints.md
├── deployment/                 # Deployment guides
│   ├── overview.md
│   ├── docker.md
│   └── kubernetes.md
├── standards/                  # Development standards
│   ├── git.md
│   ├── code-style.md
│   └── testing.md
├── best-practices.md           # Best practices guide
├── troubleshooting.md          # Common issues
└── contributing.md             # This file

File Naming​

  • Use kebab-case for file names: getting-started.md
  • Use descriptive names that reflect the content
  • Keep names short but meaningful

🔧 Technical Guidelines​

Code Examples​

Language-Specific Guidelines​

Go Code

// Always include package declaration
package main

import (
    "context"
    "fmt"
    "time"
)

// Use proper error handling
func example(ctx context.Context) error {
    if err := doSomething(); err != nil {
        return fmt.Errorf("failed to do something: %w", err)
    }
    return nil
}

TypeScript/React Code

// Use proper TypeScript types
interface User {
  id: string;
  name: string;
  email: string;
}

// Use functional components
export const UserCard: React.FC<UserCardProps> = ({ user }) => {
  return (
    <div className='user-card'>
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  );
};

SQL Code

-- Use proper SQL formatting
SELECT
    u.id,
    u.name,
    u.email,
    u.created_at
FROM users u
WHERE u.active = true
ORDER BY u.created_at DESC;

Images and Assets​

Image Guidelines​

  • Use descriptive file names: architecture-overview.png
  • Optimize images for web (compress when possible)
  • Include alt text for accessibility
  • Use appropriate formats (PNG for diagrams, JPG for photos)

Image Placement​

![Architecture Overview](/img/architecture-overview.png 'System Architecture Diagram')

Diagrams and Charts​

Mermaid Diagrams​

```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[User Service]
    C --> D[Database]
```

## 📋 Review Process

### Before Submitting

1. **Self-Review**: Read through your changes
2. **Test Links**: Ensure all internal links work
3. **Check Formatting**: Verify markdown syntax
4. **Update Sidebar**: If adding new pages, update sidebar configuration

### Pull Request Guidelines

#### PR Title
Use conventional commit format:

docs: add user authentication guide docs: update getting started instructions docs: fix broken links in API documentation


#### PR Description
Include:
- **Summary**: Brief description of changes
- **Motivation**: Why these changes are needed
- **Changes**: List of specific changes made
- **Testing**: How you tested the changes
- **Screenshots**: For UI changes (if applicable)

#### Example PR Description
```markdown
## Summary
Adds comprehensive user authentication guide for new developers.

## Motivation
New team members need clear instructions for implementing authentication in our applications.

## Changes
- Added new authentication guide with step-by-step instructions
- Included code examples for JWT implementation
- Added security best practices section
- Updated sidebar to include new guide

## Testing
- Verified all links work correctly
- Tested code examples locally
- Reviewed formatting and structure

🎯 Content Priorities​

High Priority​

  • Getting Started Guides: Essential for new developers
  • Architecture Documentation: System design and patterns
  • API Documentation: Complete API reference
  • Troubleshooting: Common issues and solutions

Medium Priority​

  • Best Practices: Advanced development patterns
  • Code Examples: Practical implementation examples
  • Integration Guides: Third-party service integration
  • Performance Guides: Optimization and monitoring

Low Priority​

  • Historical Context: Why certain decisions were made
  • Advanced Topics: Niche or specialized content
  • Community Content: User-contributed guides

🚀 Getting Started as a Contributor​

1. Fork the Repository​

  1. Go to the GitHub repository
  2. Click "Fork" to create your copy
  3. Clone your fork locally

2. Set Up Development Environment​

# Clone your fork
git clone https://github.com/your-username/tech-docs.git
cd tech-docs

# Install dependencies
pnpm install

# Start development server
pnpm start

3. Make Your Changes​

  1. Create a new branch for your changes
  2. Make your edits
  3. Test locally with the development server
  4. Commit your changes with a clear message

4. Submit Your Contribution​

  1. Push your branch to your fork
  2. Create a pull request
  3. Wait for review and feedback
  4. Make any requested changes
  5. Celebrate when your PR is merged! 🎉

📞 Getting Help​

Questions and Support​

  • GitHub Issues: For documentation problems or suggestions
  • Team Chat: For quick questions or discussions
  • Code Reviews: For feedback on your contributions

Resources​

🙏 Recognition​

We appreciate all contributions! Contributors will be recognized through:

  • GitHub Contributors: Automatic recognition in the repository
  • Release Notes: Mentioned in changelog for significant contributions
  • Team Recognition: Acknowledged in team meetings and communications

Thank you for helping make our documentation better! Your contributions help the entire team work more effectively and efficiently.

Happy documenting! 📚