jr2804 Documentation Standards
What I Do
Provide universal documentation standards and best practices that apply across different projects and domains.
Universal Documentation Structure
Documentation Organization
# Universal documentation structure
docs/
├── README.md # Project overview
├── architecture/ # System architecture
│ ├── overview.md # High-level architecture
│ └── components/ # Component details
├── development/ # Development guidelines
│ ├── setup.md # Development environment
│ ├── workflow.md # Development workflow
│ └── standards.md # Coding standards
├── api/ # API documentation
│ ├── reference.md # API reference
│ └── examples.md # Usage examples
└── user/ # User documentation
├── getting-started.md # Quick start guide
├── tutorials/ # Step-by-step tutorials
└── reference/ # Detailed reference
Documentation Formats
Universal Documentation Standards:
- Markdown: For most documentation (
.mdfiles) - Google Docstrings: For Python code documentation
- JSDoc: For JavaScript/TypeScript documentation
- Swagger/OpenAPI: For API documentation
# Universal Markdown Standards
## Headings
- Use ATX-style headings (#, ##, ###)
- Maintain consistent heading hierarchy
- Limit to 3-4 heading levels
## Code Blocks
```python
# Always specify language for syntax highlighting
def example_function():
"""Example with proper formatting"""
return "formatted code"
```
## Lists
- Use consistent list formatting
- Prefer hyphens for bullet points
- Use numbered lists for sequential steps
## Links
- Use relative links for internal references
- Use absolute links for external references
- Include link descriptions
When to Use Me
Use this skill when:
- Setting up documentation for new projects
- Standardizing documentation across teams
- Creating reusable documentation patterns
- Implementing maintainable documentation processes
Universal Documentation Examples
API Documentation
# Universal API Documentation Template
## Endpoint: `/api/v1/resource`
**Method:** `GET`
**Description:** Retrieve resource information
**Parameters:**
- `id` (string, required): Resource identifier
- `format` (string, optional): Response format (json, xml)
**Response:**
```json
{
"id": "string",
"name": "string",
"created_at": "datetime",
"status": "string"
}
```
**Examples:**
```bash
# Request example
curl -X GET "https://api.example.com/v1/resource?id=123&format=json"
# Response example
{
"id": "123",
"name": "Sample Resource",
"created_at": "2023-01-01T00:00:00Z",
"status": "active"
}
### Code Documentation
```python
# Universal Python docstring template
class DataProcessor:
"""Process and transform data for analysis.
This class provides methods for cleaning, normalizing, and
transforming raw data into analysis-ready formats.
Attributes:
config (dict): Configuration parameters for processing
logger (Logger): Logger instance for tracking operations
"""
def __init__(self, config=None):
"""Initialize DataProcessor with configuration.
Args:
config (dict, optional): Processing configuration.
Defaults to default configuration.
Raises:
ValueError: If configuration is invalid
"""
self.config = config or self._get_default_config()
self.logger = self._setup_logger()
self._validate_config()
Tutorial Documentation
# Universal Tutorial Template
## Tutorial: Getting Started with [Feature]
### Prerequisites
- Basic understanding of [related concept]
- [Software] version [version] installed
- Access to [required resources]
### Step 1: Setup
1. Install required dependencies
```bash
pip install required-package
```
2. Configure your environment
```bash
export ENV_VAR=value
```
### Step 2: Basic Usage
1. Import the module
```python
from package import Module
```
2. Create an instance
```python
processor = Module(config)
```
### Step 3: Advanced Features
1. Configure advanced options
```python
processor.configure_advanced(option=value)
```
2. Process data
```python
result = processor.process(data)
```
### Troubleshooting
- **Issue**: Common problem description
**Solution**: Step-by-step resolution
- **Issue**: Another common problem
**Solution**: Alternative approach
Best Practices
- Consistency: Apply same documentation standards across projects
- Maintainability: Keep documentation up-to-date with code
- Accessibility: Make documentation easy to find and navigate
- Completeness: Document all public APIs and user-facing features
Compatibility
Applies to:
- All software projects
- Any documentation system
- Cross-project standardization
- Organizational knowledge management