smom-dbis-138/docs/governance/DOCUMENTATION_STYLE_GUIDE.md

# Documentation Style Guide

**Last Updated**: 2025-01-27  
**Status**: Active

This style guide ensures consistency across all documentation in the project.

## Document Structure

### Required Header

All documentation files must start with:

```markdown
# Document Title

**Last Updated**: YYYY-MM-DD  
**Status**: Active | Deprecated | Archived

[Optional: Brief description or purpose statement]
```

### Table of Contents

- **Required for**: Documents > 100 lines
- **Format**: Use markdown links with anchor tags
- **Placement**: Immediately after header, before first section

Example:
```markdown
## Table of Contents

- [Section 1](#section-1)
- [Section 2](#section-2)
  - [Subsection 2.1](#subsection-21)
```

## Heading Hierarchy

### Standard Structure

```markdown
# Document Title (H1 - only one per document)

## Major Section (H2)

### Subsection (H3)

#### Sub-subsection (H4)

##### Minor subsection (H5 - use sparingly)
```

### Rules

- **H1**: Only for document title
- **H2**: Major sections
- **H3**: Subsections within major sections
- **H4+**: Use sparingly, only when necessary
- **Consistency**: Use same heading level for similar content across documents

## Code Blocks

### Format

- **Language tags**: Always specify language
- **Fenced blocks**: Use triple backticks (```)
- **Indentation**: Preserve original indentation
- **Line numbers**: Don't include line numbers in code

### Examples

**Good**:
````markdown
```bash
./scripts/deployment/deploy-contracts.sh
```
````

**Bad**:
````markdown
```bash
1  ./scripts/deployment/deploy-contracts.sh
2  # This is wrong
```
````

### Inline Code

- Use single backticks for: file names, commands, variables, function names
- Example: Use `PRIVATE_KEY` environment variable

## Lists

### Unordered Lists

- Use `-` (hyphen) for unordered lists
- Indent with 2 spaces for nested items
- Be consistent with list markers

### Ordered Lists

1. Use numbers for ordered lists
2. Use when sequence matters
3. Indent with 2 spaces for nested items

### List Formatting

- **Capitalization**: Capitalize first word of each item
- **Punctuation**: Use periods for complete sentences, no punctuation for fragments
- **Consistency**: Keep same format within a list

## Links

### Internal Links

- **Relative paths**: Use relative paths for internal documentation
- **Format**: `[Link Text](path/to/file.md)`
- **Anchor links**: Use for sections: `[Section Name](#section-name)`

### External Links

- **Full URLs**: Use full URLs for external links
- **Format**: `[Link Text](https://example.com)`
- **Context**: Always provide context, don't use "click here"

### Link Text

**Good**: See [Deployment Guide](deployment/DEPLOYMENT.md) for details.  
**Bad**: Click [here](deployment/DEPLOYMENT.md) for details.

## Date Formats

- **Format**: YYYY-MM-DD (ISO 8601)
- **Example**: 2025-01-27
- **Consistency**: Use same format throughout

## Status Indicators

### Document Status

- **Active**: Current, maintained documentation
- **Deprecated**: Outdated but kept for reference
- **Archived**: Historical documentation

### Task Status

- **✅**: Completed
- **⏳**: In Progress
- **❌**: Failed/Blocked
- **⏸️**: Paused
- **📋**: Pending

## Emphasis

- **Bold** (`**text**`): For important terms, file names, commands
- *Italic* (`*text*`): For emphasis, variable names, technical terms
- `Code` (backticks): For code, commands, file paths

## Tables

### Format

```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |
```

### Rules

- Align columns with pipes
- Use header row
- Keep tables simple and readable
- Use consistent alignment

## Block Quotes

- Use `>` for block quotes
- Use for notes, warnings, important information
- Can be nested with `>>`

Example:
```markdown
> **Note**: This is important information.
> 
> Additional context here.
```

## Cross-References

### Related Documentation

Add "Related Documentation" section where appropriate:

```markdown
> **Related Documentation**:
> - [Guide 1](path/to/guide1.md) - Description
> - [Guide 2](path/to/guide2.md) - Description
```

## Code Examples

### Best Practices

- **Test all examples**: Ensure code examples work
- **Expected output**: Show what success looks like
- **Error handling**: Include common errors and solutions
- **Version tags**: Tag with software versions when relevant
- **Copy-paste ready**: Remove placeholders where possible

### Example Format

```bash
# Example: Deploy contracts
./scripts/deployment/deploy-contracts.sh

# Expected output:
# ✅ Contracts deployed successfully
# Contract addresses:
# - WETH: 0x...
```

## Terminology

### Consistent Terms

- Use consistent terminology throughout
- Define technical terms on first use
- Use same abbreviations consistently
- Create glossary for complex terms

### Capitalization

- **Proper nouns**: Capitalize (Azure, Kubernetes, Besu)
- **Commands**: Lowercase unless part of proper noun
- **File paths**: Match actual case
- **Acronyms**: All caps (RPC, API, JSON)

## Writing Style

### Voice

- **Active voice**: Prefer active voice
- **Clear and concise**: Remove unnecessary words
- **Direct**: Get to the point quickly

### Examples

**Good**: "The script deploys the contracts."  
**Bad**: "The contracts are deployed by the script."

### Tone

- **Professional**: Maintain professional tone
- **Helpful**: Be helpful and clear
- **Accurate**: Ensure accuracy

## Prerequisites

### Format

Always clearly state prerequisites:

```markdown
## Prerequisites

- Item 1
- Item 2
- Item 3
```

## Troubleshooting

### Format

Include troubleshooting sections where appropriate:

```markdown
## Troubleshooting

### Issue Name

**Symptoms**: Description of issue

**Solution**: Steps to resolve

**Prevention**: How to avoid in future
```

## Metadata

### Required Metadata

All documents should include:

- **Last Updated**: Date
- **Status**: Active/Deprecated/Archived
- **Purpose**: Brief description (optional but recommended)

### Optional Metadata

- **Version**: Version number if applicable
- **Author**: Author name
- **Review Date**: Next review date

## File Naming

### Conventions

- **UPPERCASE_WITH_UNDERSCORES.md**: For major documents
- **lowercase-with-dashes.md**: For guides and how-tos
- **Descriptive**: Use clear, descriptive names
- **Consistent**: Follow existing patterns

## Images and Diagrams

### Format

- **Placement**: Store in `docs/images/` or `docs/diagrams/`
- **Alt text**: Always include alt text
- **Format**: Use markdown image syntax
- **Size**: Optimize for web

```markdown
![Alt text](images/diagram.png)
```

## Checklists

### Format

Use checkboxes for actionable items:

```markdown
- [ ] Task 1
- [ ] Task 2
- [x] Completed task
```

## Version Control

### Git Conventions

- **Commit messages**: Clear, descriptive
- **File changes**: Document in commit message
- **Related docs**: Update related docs together

## Review Checklist

When reviewing documentation, check:

- [ ] Follows style guide
- [ ] Has required metadata
- [ ] Has table of contents (if > 100 lines)
- [ ] Links work correctly
- [ ] Code examples tested
- [ ] Consistent formatting
- [ ] Clear and concise
- [ ] Accurate information
- [ ] Cross-references added
- [ ] Prerequisites stated

## Examples

### Good Documentation

```markdown
# Deployment Guide

**Last Updated**: 2025-01-27  
**Status**: Active

## Table of Contents

- [Prerequisites](#prerequisites)
- [Deployment Steps](#deployment-steps)

## Prerequisites

- Azure CLI installed
- Terraform >= 1.0

## Deployment Steps

1. Run the deployment script:
   ```bash
   ./scripts/deployment/deploy.sh
   ```

2. Verify deployment:
   ```bash
   ./scripts/verify.sh
   ```

> **Related Documentation**:
> - [Architecture Guide](architecture/ARCHITECTURE.md) - System architecture
> - [Configuration Guide](configuration/CONFIGURATION_INDEX.md) - Configuration options
```

## Updates

This style guide should be reviewed and updated quarterly or as needed.

---

**Last Updated**: 2025-01-27  
**Next Review**: 2025-04-27