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:

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

## Table of Contents

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

Heading Hierarchy

Standard Structure

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

```bash
./scripts/deployment/deploy-contracts.sh
```

Bad:

```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 for details.
Bad: Click here 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

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

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

Cross-References

Related Documentation

Add "Related Documentation" section where appropriate:

> **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

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

## Prerequisites

- Item 1
- Item 2
- Item 3

Troubleshooting

Format

Include troubleshooting sections where appropriate:

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

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

Checklists

Format

Use checkboxes for actionable items:

- [ ] 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

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

   ./scripts/verify.sh
   

Related Documentation:

• Architecture Guide - System architecture
• Configuration Guide - 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