Labeling for Documentation — Complete Guide

Labeling assigns names to navigation items, categories, and links. Learn how to create clear, consistent labels that match user vocabulary and improve findability.

What You'll Learn

You will learn labeling principles, how to create a controlled vocabulary, how to test labels with users, and how to maintain labeling consistency.

Why It Matters

Labels are how users identify content. Inconsistent or unclear labels force users to guess. Clear labels make navigation effortless.

Real-World Use

DodaTech uses consistent labels across all tutorials: "What You'll Learn," "Why It Matters," "Real-World Use," "Common Mistakes," "Practice Questions," "FAQ," "Mini Project," and "What's Next."

flowchart LR
  A[Labeling] --> B[Principles]
  A --> C[Creation]
  A --> D[Testing]
  B --> E[Clarity]
  B --> F[Consistency]
  B --> G[User Vocabulary]
  C --> H[Controlled Vocabulary]
  C --> I[Label Glossary]
  D --> J[User Testing]
  D --> K[Analytics]
  E:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Labeling Principles

Principle of Clarity

Labels must be immediately understandable. Do not make users think about what a label means.

Principle of Consistency

The same concept must always use the same label.

def check_label_consistency(pages, expected_label):
    violations = []
    for page in pages:
        if page['category'] == expected_label:
            continue
        # Check if page uses different label for same concept
        for alt_label in page.get('alternative_labels', []):
            if alt_label == expected_label:
                violations.append(f"Page {page['title']} uses '{page['category']}' instead of '{expected_label}'")
    return violations

pages = [
    {'title': 'Python Intro', 'category': 'Getting Started'},
    {'title': 'Python Setup', 'category': 'Getting Started', 'alternative_labels': ['Quick Start']},
    {'title': 'Python Install', 'category': 'Quick Start'},  # inconsistent
]
print(check_label_consistency(pages, 'Getting Started'))

Expected output:

["Page Python Install uses 'Quick Start' instead of 'Getting Started'"]

Principle of User Vocabulary

Labels should match how users talk about the topic, not internal jargon.

Creating Labels

Label Source

Labels come from user research, not internal discussions.

## Label Creation Process

1. Collect terms from user research (interviews, surveys, search queries)
2. Identify common patterns and synonyms
3. Choose preferred terms
4. Document in a label glossary
5. Test with users
6. Review and update annually

Label Glossary

# label-glossary.yaml
labels:
  - preferred: Getting Started
    synonyms: [Quick Start, Introduction, First Steps]
    context: Always use for beginner-oriented tutorials
    avoid: [Initialization, Onboarding, Primer]

  - preferred: API Reference
    synonyms: [API Docs, API Documentation, Reference]
    context: For auto-generated or manually written API docs
    avoid: [Endpoint Documentation, Service Spec]

  - preferred: Troubleshooting
    synonyms: [Common Issues, Error Fixes, Problems]
    context: For error resolution content
    avoid: [Diagnostic Procedures, Issue Resolution]

Testing Labels

Methods

def label_comprehension_test(label, options, correct_index):
    # Simulate user responses
    responses = []
    for user in range(20):
        import random
        response = random.choices([0, 1, 2], weights=[0.7, 0.2, 0.1])[0]
        responses.append(response)
    
    correct = sum(1 for r in responses if r == correct_index)
    comprehension_rate = correct / len(responses)
    return comprehension_rate

rate = label_comprehension_test("Getting Started", ["Beginner tutorial", "Quick start guide", "System setup"], 0)
print(f"Comprehension rate: {rate:.0%}")

Expected output:

Comprehension rate: 70%

Common Mistakes

1. Using Internal Jargon

Labels that make sense internally but not to users. Always test labels with external users.

2. Inconsistent Labels

Calling it "Tutorial" in one place and "Guide" in another. The same concept must use the same label everywhere.

3. Creative Labels

Being clever with labels sacrifices clarity. "Knowledge Nest" is less clear than "Documentation."

4. No Label Glossary

Without documentation, different writers invent different labels. Maintain a label glossary.

5. Never Testing Labels

Labels based on assumptions are often wrong. Test every label with real users.

Practice Questions

1. What are the three labeling principles?

Clarity, consistency, and user vocabulary.

2. What is a label glossary?

A document that defines preferred labels, synonyms, and terms to avoid.

3. Why should labels match user vocabulary?

Users navigate by looking for terms they understand. If labels do not match their vocabulary, they cannot find content.

4. How do you test label comprehension?

Show users a label and ask them to describe what content they expect to find. Measure accuracy.

5. Challenge: Audit the labels on a documentation site. Find three inconsistent labels, propose replacements, and create a label glossary entry for each.

FAQ

Mini Project

Create a label glossary for a documentation site. Define 10 preferred labels with synonyms and terms to avoid. Test 3 labels with 5 users and document the results.

What's Next

Now that you understand labeling, learn Card Sorting to understand user mental models. Then study Tree Testing to validate navigation.