socktop-webterm/docs/CONTRIBUTING.md

# Contributing to socktop Documentation

Thank you for your interest in improving the socktop documentation!

## Quick Start

1. **Install documentation tools:**
   ```bash
   ./setup-docs.sh
   ```

2. **Make your changes** to the relevant `.md` files in `src/`

3. **Test locally:**
   ```bash
   mdbook serve
   ```
   Open http://localhost:3000 to preview

4. **Submit a pull request** with your changes

## Documentation Structure

```
docs/src/
├── SUMMARY.md              # Table of contents (edit when adding pages)
├── introduction.md         # Project overview
├── installation/           # Installation guides
├── usage/                  # Usage documentation
├── security/              # Security guides
└── advanced/              # Advanced topics
```

## Writing Guidelines

### Style Guide

- **Be clear and concise** - Users want answers, not prose
- **Use active voice** - "Run the command" not "The command should be run"
- **Include examples** - Show, don't just tell
- **Test your code** - Verify all commands and code examples work
- **Link related content** - Help users discover related topics

### Markdown Formatting

Use standard Markdown with these conventions:

#### Code Blocks

Always specify the language:

~~~markdown
```bash
cargo install socktop
```

```rust
use socktop_connector::*;
```

```toml
[profiles.server]
url = "ws://localhost:3000"
```
~~~

#### Command Examples

Show both the command and expected output:

```bash
# Check version
socktop --version
# Output: socktop 1.50.2
```

#### Admonitions

Use clear callouts for important information:

```markdown
**Note:** This requires root permissions.

**Warning:** This will delete all data.

**Tip:** Use Ctrl+C to exit.
```

#### Links

Use descriptive link text:

```markdown
✅ Good: See [Agent Service Setup](../installation/agent-service.md)
❌ Bad:  Click [here](../installation/agent-service.md)
```

### Page Structure

Each page should follow this template:

```markdown
# Page Title

Brief introduction explaining what this page covers.

## Section 1

Content...

### Subsection 1.1

More specific content...

## Section 2

More content...

## Next Steps

- [Related Topic 1](./related-topic-1.md)
- [Related Topic 2](./related-topic-2.md)

<!-- TODO: Add more documentation -->
<!-- TODO: Add specific improvements needed -->
```

## Adding New Pages

1. **Create the file** in the appropriate directory:
   ```bash
   touch src/installation/new-guide.md
   ```

2. **Add to SUMMARY.md** in the correct section:
   ```markdown
   # Installation
   
   - [Quick Start](./installation/quick-start.md)
   - [New Guide](./installation/new-guide.md)  # Add here
   ```

3. **Write the content** following the guidelines above

4. **Test the build:**
   ```bash
   mdbook build
   mdbook serve
   ```

5. **Check for broken links:**
   - Navigate to your new page
   - Click all internal links
   - Verify they work correctly

## Updating Existing Pages

1. **Edit the `.md` file** directly

2. **Maintain consistency:**
   - Keep the same writing style
   - Don't remove useful examples
   - Update version numbers if needed

3. **Update related pages** if your changes affect them

4. **Test thoroughly:**
   ```bash
   mdbook serve
   ```

## TODO Comments

Use TODO comments to mark areas needing work:

```markdown
<!-- TODO: Add more documentation -->
<!-- TODO: Add screenshots -->
<!-- TODO: Add video demonstration -->
<!-- TODO: Expand with more examples -->
```

These help identify areas for future improvement.

## Screenshots and Images

When adding images:

1. **Create an `images/` directory** in the relevant section:
   ```bash
   mkdir -p src/installation/images
   ```

2. **Use descriptive filenames:**
   ```
   ✅ Good: installation-apt-repository.png
   ❌ Bad:  screenshot1.png
   ```

3. **Reference in Markdown:**
   ```markdown
   ![APT Repository Setup](./images/installation-apt-repository.png)
   ```

4. **Optimize images:**
   - Use PNG for screenshots
   - Use JPG for photos
   - Compress to reduce file size
   - Maximum width: 1200px

## Code Examples

### Shell Scripts

```bash
#!/bin/bash
# Always include a description comment

# Use descriptive variable names
SERVER_URL="ws://localhost:3000"

# Show error handling
if ! command -v socktop &> /dev/null; then
    echo "Error: socktop not installed"
    exit 1
fi

# Clear, commented steps
socktop "$SERVER_URL"
```

### Rust Code

```rust
// Include necessary imports
use socktop_connector::*;

// Add comments for complex logic
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to agent
    let mut connector = connect_to_socktop_agent("ws://localhost:3000/ws").await?;
    
    // Request metrics
    match connector.request(AgentRequest::Metrics).await {
        Ok(AgentResponse::Metrics(m)) => {
            println!("CPU: {:.1}%", m.cpu_total);
        }
        Err(e) => eprintln!("Error: {}", e),
        _ => unreachable!(),
    }
    
    Ok(())
}
```

### Configuration Files

Always show complete, working examples:

```toml
# ~/.config/socktop/profiles.toml

[profiles.production]
url = "wss://prod.example.com:3000"
token = "your-token-here"
ca_cert = "/etc/ssl/certs/ca.pem"
verify_tls = true
```

## Testing Your Changes

### Local Preview

```bash
# Start development server
mdbook serve

# Open in browser
# Navigate to your changed pages
# Verify formatting and links
```

### Build Test

```bash
# Clean build
rm -rf book/
mdbook build

# Check for warnings
# Fix any broken links or errors
```

### Cross-Reference Check

- Click all internal links
- Verify they point to correct pages
- Check that anchor links work
- Test external links

## Submitting Changes

1. **Commit with clear messages:**
   ```bash
   git add docs/src/installation/new-guide.md
   git commit -m "docs: Add new installation guide for Docker"
   ```

2. **Push to your fork:**
   ```bash
   git push origin docs/docker-install
   ```

3. **Create pull request:**
   - Describe what you added/changed
   - Explain why it's needed
   - Link to any related issues

## Documentation Priorities

Focus on these high-impact areas:

1. **Missing content** marked with TODO comments
2. **User-reported confusion** from issues/discussions
3. **New features** that need documentation
4. **Common questions** that arise frequently
5. **Error scenarios** and troubleshooting

## Getting Help

- **Questions?** Open a discussion on GitHub
- **Found a bug in docs?** Open an issue with the "documentation" label
- **Want to discuss major changes?** Start with an issue before writing

## Recognition

All documentation contributors will be acknowledged in:
- Git history
- Contributors list
- Release notes (for significant contributions)

## Thank You!

Good documentation is crucial for project success. Your contributions help users get started faster and use socktop more effectively. Thank you for helping improve the documentation! 🎉