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:

   ./setup-docs.sh
   

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

3. Test locally:

   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:

```bash
cargo install socktop
```

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

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

Command Examples

Show both the command and expected output:

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

Admonitions

Use clear callouts for important information:

**Note:** This requires root permissions.

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

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

Links

Use descriptive link text:

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

Page Structure

Each page should follow this template:

# 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:

   touch src/installation/new-guide.md
   

2. Add to SUMMARY.md in the correct section:

   # 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:

   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:

   mdbook serve
   

TODO Comments

Use TODO comments to mark areas needing work:

<!-- 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:

   mkdir -p src/installation/images
   

2. Use descriptive filenames:

   ✅ Good: installation-apt-repository.png
   ❌ Bad:  screenshot1.png
   

3. Reference in 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

#!/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

// 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:

# ~/.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

# Start development server
mdbook serve

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

Build Test

# 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:

   git add docs/src/installation/new-guide.md
   git commit -m "docs: Add new installation guide for Docker"
   

2. Push to your fork:

   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! 🎉