Style Guide Adherence for Contributors

In this tutorial, you will learn about Style Guide Adherence for Contributors. We cover key concepts, practical examples, and best practices to help you master this topic.

Style guide adherence ensures all documentation contributions are consistent in voice, tone, formatting, and structure regardless of who wrote them.

What You'll Learn

You will learn how to read and apply a style guide, common style rules for documentation, and how to check your contributions against style requirements.

Why It Matters

Inconsistent documentation confuses readers. A style guide creates predictability. Contributors who follow the style guide produce content that fits seamlessly.

Real-World Use

DodaTech's style guide covers voice, tone, formatting, required sections, and terminology. Every PR is checked against the style guide before merging.

flowchart LR
  A[Style Guide Adherence] --> B[Voice and Tone]
  A --> C[Formatting Rules]
  A --> D[Required Sections]
  A --> E[Review Process]
  B --> F[Active Voice]
  B --> G[Direct Address]
  C --> H[Headings]
  C --> I[Code Blocks]
  D --> J[Minimum Sections]
  D --> K[Structure]
  E --> L[Automated Checks]
  E --> M[Manual Review]
  F:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Common Style Rules

Voice

Tone

## Tone Guidelines

- Direct and educational
- No marketing language
- No emojis
- No jargon without explanation
- Be concise but complete

Formatting

def check_formatting_rules(content):
    issues = []
    if content.count('## ') > 1:
        issues.append('Only one H2 should exist per section')
    if '```' not in content:
        issues.append('Code examples are required')
    if len(content) < 1000:
        issues.append('Content should be at least 1000 words')
    return issues

content = "# Title\n\nSome content"
for issue in check_formatting_rules(content):
    print(issue)

Expected output:

Code examples are required
Content should be at least 1000 words

Required Sections

Most documentation projects require specific sections in every page.

required_sections:
  - section: Hook
    content: "What You'll Learn, Why It Matters, Real-World Use"
    required: true
    
  - section: Common Mistakes
    content: "At least 5 common mistakes"
    required: true
    
  - section: Practice Questions
    content: "At least 3 questions with answers"
    required: true
    
  - section: FAQ
    content: "At least 5 FAQ items"
    required: true
    
  - section: Mini Project
    content: "A practical exercise"
    required: true

Checking Adherence

Automated Checks

# Lint markdown formatting
npx markdownlint-cli2 content/

# Check required sections
python3 scripts/check-sections.py content/

Manual Review Checklist

## Style Review Checklist

- [ ] Active voice throughout
- [ ] Reader addressed as "you"
- [ ] Present tense used consistently
- [ ] No emojis
- [ ] Code blocks have language tags
- [ ] Headings follow hierarchy (H1 > H2 > H3)
- [ ] Links are descriptive
- [ ] No broken links

Common Mistakes

1. Not Reading the Style Guide

Contributors who skip the style guide produce content that needs significant rework. Always read it first.

2. Inconsistent Terminology

Using "tutorial" in one paragraph and "guide" in another for the same type of content.

3. Code Blocks Without Language Tags

# Bad: ``` without language
# Good: ```python

4. Passive Voice

"The form should be filled out by the user" should be "You must fill out the form."

5. Missing Required Sections

Submitting a tutorial without a Common Mistakes or FAQ section. Check the requirements before submitting.

Practice Questions

1. Why is style guide adherence important for documentation?

It ensures consistency across all pages regardless of who wrote them, creating a predictable experience for readers.

2. What is an example of active voice?

"The function returns a list" is active. "A list is returned" is passive.

3. What should code blocks include?

A language tag for syntax highlighting: python, JavaScript, etc.

4. How do you check style adherence?

Automated tools like markdownlint and manual review using a checklist.

5. Challenge: Create a style guide checklist for documentation contributors. Include 10 items covering voice, formatting, required sections, and links.

FAQ

Mini Project

Create a one-page style guide for documentation contributors. Include voice, tone, formatting, required sections, and a review checklist with 10 items.

What's Next

Now that you understand style guides, learn Code of Conduct for community participation. Then study Issue Tracking for Docs.