Style Guide

This guide defines content standards for the API Docs Glossary: what makes a good term entry, how to format definitions, capitalization rules, and writing conventions. All contributions must follow these standards to maintain consistency and quality.

For technical setup and the pull request process, visit the Contribution Guide.

Glossary Philosophy

The API Docs Glossary exists to demystify API documentation terminology for writers, developers, and technical communicators. Good glossary entries:

Aim for clarity over comprehensiveness - brief, scannable definitions that get readers oriented quickly
Connect concepts - show how terms relate to each other through thoughtful linking
Focus on API documentation context - explain why terms matter specifically for documenting APIs
Serve real needs - address terms readers actually encounter in API documentation work

This glossary isn't an exhaustive technical reference. It's a practical resource for people learning or working in API documentation who need quick, reliable definitions.

Contribution Content Strategy

Documentation improvements are always welcome. Contributions must benefit API Docs Glossary readers. Contributions are especially welcome if they:

add new API documentation terms with clear definitions
improve clarity of existing definitions
add relevant examples to existing terms
fix technical inaccuracies

Before contributing, create an issue to discuss additions or changes.

Add a new glossary term

Most terms live in existing category files. To add a new term:

Identify which category file the term belongs in:
- quick-reference.md - Common terms, concise definitions
- core-concepts.md - Fundamental API documentation concepts
- api-types-architectures.md - Different architectural patterns and protocols
- ai-and-apis.md - AI technologies, concepts relevant to API documentation
- tools-techniques.md - Tools, software, methods
- workflows-methodologies.md - Development, documentation workflows for API projects
- frameworks-strategy.md - Conceptual models, strategic approaches for API documentation work
- writing-style.md - Language conventions, tone guidelines, rhetorical approaches

Add the term using this format:

## Term Name

**Definition**: Brief, clear definition

**Purpose**: Why this matters for API documentation

**Example**: Real-world example or use case (optional)

**Related Terms**: Link to other relevant terms

**Source**: Acknowledgement of the information's origin

Place the term alphabetically within its section or at the end of the appropriate subsection
Test locally with npm start to ensure formatting looks correct

Acronyms

Acronym use is most impactful in headings because headings serve as both navigation labels and anchor links in Docusaurus. Consider the relationship of the glossary term's official name and how someone is most likely to reference it in conversation. Use the most recognizable form of a term in headings to create clean, scannable navigation and maintainable anchor links.

Rules

Use the acronym alone when it's widely recognized and commonly used:

✅ ## API not ## API (Application Programming Interface)
✅ ## HTTP not ## HTTP (Hypertext Transfer Protocol)
✅ ## JSON not ## JSON (JavaScript Object Notation)
✅ ## REST API not ## REST (Representational State Transfer) API

Rationale: acronyms in headings create shorter, cleaner navigation panels and anchor links; [HTTP](#http) is easier to write and maintain than [HTTP](#http-hypertext-transfer-protocol)

Explain the full name in the definition field immediately after the heading:

## REST API

**Definition**: acronym for *RE*presentational State Transfer
application programming interface...

## gRPC API

**Definition**: uses gRPC - _Google's Remote Procedure Call_ - framework...

<!-- definition structure in Quick Reference-->

### UI

- acronym for user interface
- space where interactions between humans and machines occur

**Glossary Term Entry Location**: [Tools & Techniques - UI](tools-techniques.md#ui)

Use the full name when the acronym isn't widely recognized or when the full name is more commonly used:

✅ ## Critical Chain Project Management not ## CCPM
✅ ## Waterfall not ## Waterfall Project Management Methodology
✅ ## guerilla usability testing not ## GUT

When unsure, check common usage patterns:

Search API documentation, technical articles, and MDN Web Docs
If the acronym appears more frequently than the full name, use the acronym
If the full name is more recognizable, use the full name
Consider the glossary target audience - what term would they search for?

Never use parenthetical expansions in headings - they clutter navigation and create unnecessarily long anchor links:

❌ ## SOAP (Simple Object Access Protocol) API
✅ ## SOAP API with definition explaining "Simple Object Access Protocol"
❌ ## URI (Uniform Resource Identifier)
✅ ## URI with definition explaining "Uniform Resource Identifier"

Anchor Link Consistency

Headings become anchor links automatically. Keep them concise to:

streamline cross-referencing between terms
reduce errors when creating links
improve navigation panel readability

Example of the difference:

Heading Style	Anchor Link	Usability
`## HTTP`	`[HTTP](#http)`	✅ Short, clear, maintainable
`## HTTP (Hypertext Transfer Protocol)`	`[HTTP](#http-hypertext-transfer-protocol)`	❌ Long, error-prone
`## URL`	`[URL](#url)`	✅ Short, clear, maintainable
`## URL (Uniform Resource Locator)`	`[URL](#uniform-resource-locator-url)`	❌ Long, error-prone

Updating Anchor Links

When renaming terms or reorganizing the glossary, don't forget to update all anchor links that reference the changed term. Use grep to find all instances in Markdown files:

Find all links to a specific anchor:

grep -rn "](#anchor-name)" . --include="*.md"

Example - find links to #openapi-specification-oas:

grep -rn "](#openapi-specification-oas)" . --include="*.md"

Break down the command:

grep - search tool
-r - recursive, searches all subdirectories
-n - shows line numbers in results
"](#anchor-name)" - the pattern to find, Markdown link syntax
. - current directory
--include="*.md" - only search Markdown files, exclude config files

After finding all instances:

Review each result to determine if it needs updating
Some links may need just the anchor changed: #new-anchor
Others may need the specific file in the path changed: glossary.md#anchor
Update each link manually based on context

Troubleshooting Broken Anchor Links

After updating headings, run npm run build to verify that all anchor links are working. Docusaurus reports any broken anchors it finds.

Example build output with broken anchors:

[WARNING] Docusaurus found broken anchors!
- Broken anchor on source page path = /docs/tools-techniques:
   -> linking to #pull-request-pr

Find and fix broken anchors:

Run the build command to identify broken links:
```
npm run build
```

Use grep to find all instances of the old anchor format. Common patterns when removing acronyms from headings:

# Find links with acronym suffixes that need updating
grep -rn "#guerrilla-usability-testing-gut" . --include="*.md"
grep -rn "#pull-request-pr" . --include="*.md"
grep -rn "#openapi-specification-oas" . --include="*.md"

# Find cross-file links that may have changed
grep -rn "core-concepts#rest" . --include="*.md"

Update each link manually to match the new heading format
Run npm run build again to verify the corrections

Common causes of broken anchors:

updated a heading but forgot to update the Related Terms links
removed acronyms from headings but left them in anchor links
changed file organization but didn't update cross-file references
typos in manually created anchor links

Capitalization

Use consistent capitalization to maintain clarity and professionalism.

Term Rules by Category

Category	Rule	Examples
Proper noun & products	Always capitalize official names	Agile, Git, GitHub
Official tools	Capitalize specific product names	GitHub Desktop, Swagger Editor
Acronyms	Always capitalize	API, GUI, HTTP/HTTPS, REST
Brand-specific	Follow the product's capitalization	cURL, json-server, macOS
Common terms	Use lowercase	branch, commit, repository
Git commands	Use lowercase	pull, push, rebase
Generic phrases	Use lowercase	merge conflict, pull request, version control
File types	Use lowercase unless referring to the language	`markdown` file, but Markdown language

Headings

Match term headings with the capitalization of the term itself:

## branch not ## Branch
## GitHub not ## github
##REST API not ##REST api

Category and section headings use different capitalization based on their function:

Labels and titles use title case: # Core Concepts, # Tools & Techniques, ## Glossary Philosophy
Task-based or action phrases use sentence case: ## Add a new glossary term, ## Create a new category

Rationale: term headings follow the natural capitalization of the term definition - lowercase for common terms, proper capitalization for brands and/or acronyms; category headings use title case because they function as navigation labels and section titles rather than as terms themselves

Note: this approach intentionally breaks Vale's Google.Headings rule, which prefers sentence-case headings; for this glossary, matching term capitalization and using title case for categories improves clarity and usability

When breaking the Vale's Google.Headings rule, add the following comment below said heading:

<!-- ignore this Vale capitalization error, see Style Guide #Headings-->

Definition and Purpose Fields

Use sentence fragments and/or phrases rather than complete sentences. Start with lowercase unless the word is a proper noun:

## branch

**Definition**: a parallel version of a repository that
enables work on changes without affecting the main codebase

**Purpose**: enables multiple developers to work on different
features simultaneously in API documentation workflows

Rare exception: if a definition must be a complete sentence for clarity, capitalize the first word per standard sentence rules, even if it's the term itself:

## rebase

**Definition**: Rebase updates the base commit from
which a branch was created.

Link related terms to help readers navigate connected concepts and build understanding of how terms relate to each other. Include 3-6 related terms per entry. Too few misses valuable connections, while too many overwhelms and dilutes relevance. Link terms that are:

Directly connected: terms used together in workflows, such as branch → merge, commit, rebase
Prerequisite concepts: terms readers need to understand first, such as REST API → HTTP, JSON
Higher-level concepts: category terms that provide context, such as cURL → API testing, command line

Link Format

list terms in alphabetical or local order: prerequisites first, then workflow-related, then alternatives
use the exact term name as it appears in its heading
separate with commas: **Related Terms**: branch, commit, merge, rebase

Linking Syntax

For terms in the same file:

**Related Terms**: [term name](#term-name)

Example: **Related Terms**: [API](#api), [REST API](#rest-api)

For terms in different files:

**Related Terms**: [term name](filename.md#term-name)

Example: **Related Terms**: [Git](tools-techniques.md#git), [GitHub](tools-techniques.md#github)

Important:

the anchor link - #term-name - must exactly match the heading
use lowercase and hyphens for multi-word terms: #http-status-codes
acronyms are lowercase in anchors: #rest-api not #REST-API
test all links locally with npm start before submitting
only link to terms that exist - don't list terms in the Related Terms list that don't have glossary entries

Source References

Provide specific, verifiable sources for all term definitions and information. Sources acknowledge where information originates and allow readers to explore topics further.

Format Guidelines

For web sources, use descriptive link text with the full URL:

**Source**: [Organization Name: "Page Title"](https://full-url.com)

Example:

**Source**: [IETF RFC 9110 - HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)

For course materials, include course name, module, lesson, and topic title:

**Source**: Course Name: Module X, Lesson Y, "Topic Title"

Example:

**Source**: UW API Docs: Module 5, Lesson 1, "REST API Fundamentals"

For many sources, use a bulleted list:

**Sources**:

- [Organization: "Title"](https://url.com)
- Course Name: Module X, Lesson Y, "Topic"

Example:

**Sources**:

- [University of Washington: "AI + Teaching"](https://teaching.washington.edu/course-design/ai/)
- UW API Docs: Module 1, Lesson 4, "Intro to AI and API docs"

Best Practices

be as specific as possible - include authors' names, exact page titles, section names, or RFC numbers
for official specifications - HTTP, OpenAPI - link to the authoritative source
for course materials without public URLs, provide enough detail for verification
if citing forum discussions or informal sources, note the context: "UW API Docs Canvas Forum"
when a term draws from many sources, sort them alphabetically

Voice and Tone

Write in active voice without first-person pronouns to maintain directness and professional tone.

Active Voice

Use active voice where the subject performs the action:

✅ "Git tracks changes in files"
❌ "Changes in files are tracked by Git"
✅ "Developers use branches to isolate work"
❌ "Branches are used by developers to isolate work"

Avoid first-person pronouns

Write from a neutral, instructional perspective:

❌ "We use branches to isolate work"
❌ "You should commit changes frequently"
✅ "Branches isolate work without affecting the main codebase"
✅ "Frequent commits create detailed project history"

Purpose and Example Fields Exception

Use second person - "users," "developers," "writers" - when describing who performs actions:

✅ **Purpose**: enables developers to work on different features simultaneously
✅ **Example**: developers create a branch named docs/add-webhook-guide

Clarity Over Rules

If passive voice improves clarity or readability, use it - but this is likely rare. When in doubt, rewrite in active voice.

Add a term to Quick Reference

Note: every Quick Reference entry must have a corresponding full entry in a category file; don't create Quick Reference entries for terms that lack detailed definitions elsewhere in the glossary

The Quick Reference page provides concise definitions and filing locations for commonly used terms. Add terms to Quick Reference when they meet these criteria:

Frequently referenced across many contexts
Benefit from a brief, scannable definition
Already have a full entry in one of the main category files

To add a term to Quick Reference:

Add the term alphabetically under the appropriate letter heading in quick-reference.md

Use this format:

   ### term name

   - category or ecosystem context
   - brief definition or key characteristic

   **Glossary Term Entry Location**: [Category Name - term name](category-file.md#term-name)

   ---

Link to the full entry using the syntax: [Link Text](page-name.md#header-id)
- page-name.md is the category filename
- header-id is the exact heading, including capitalization
- Match the header-id to the heading exactly as it appears in the target file

Example:

   ### Waterfall

   - project management method
   - traditional, sequential, linear, idealistic

   **Glossary Term Entry Location**: [Workflows & Methodologies - Waterfall](workflows-methodologies.md#waterfall)

   ---

Test the link locally with npm start to ensure it navigates correctly to the full entry

Create a new category

If the term doesn't fit existing categories and warrants a new one:

Create a new Markdown file in the docs/ directory, such as advanced-topics.md

Add a category overview following this format:

# Category Name
<!-- ignore this Vale capitalization error, see Style Guide #Headings-->

Brief description of what this category covers. This section explains
the scope and purpose, helping readers understand what types of terms
they'll find here and why these concepts matter for API documentation.

<!-- Example overview with value proposition -->
# Tools & Techniques

Essential tools and methods for API documentation workflows.
From version control to interactive documentation generators,
this section covers the software, platforms, and practices used
to create, test, validate, and publish API documentation.

Add the term and/or terms using the format described in Add a new glossary term section

Add the new file to sidebars.ts in the logical position within the array:

items: [
  'quick-reference',
  'core-concepts',
  'api-types-architectures', // New category added here
  'ai-and-apis',
  'tools-techniques',
  // ... other categories
],

Update this style-guide.md by adding the new term category to the list in the Add a new glossary term section:

1. Identify which category file the term belongs in:

- `quick-reference.md` - Common terms, concise definitions
- `core-concepts.md` - Fundamental API documentation concepts
- `api-types-architectures.md` - Different architectural patterns and protocols
- `ai-and-apis.md` - AI technologies, concepts relevant to API documentation
<!--> ... continue list-->

Update the contribution-guide.md by adding the new term category to any lists or descriptions of the glossary structure
Update getting-started.md by adding the new term category to any lists or descriptions of the glossary structure
Update the README.md by adding the new category to the Topics section with a brief description of the category contents and a link to its documentation page
Test the navigation locally with npm start to ensure:
- the new category appears correctly in navigation
- all links work properly
- the new category is accessible from all relevant locations

Glossary Philosophy​

Contribution Content Strategy​

Add a new glossary term​

Acronyms​

Rules​

Anchor Link Consistency​

Updating Anchor Links​

Troubleshooting Broken Anchor Links​

Capitalization​

Term Rules by Category​

Headings​

Definition and Purpose Fields​

Related Terms Linking Strategy​

Link Format​

Linking Syntax​

Source References​

Format Guidelines​

Best Practices​

Voice and Tone​

Active Voice​

Avoid first-person pronouns​

Purpose and Example Fields Exception​

Clarity Over Rules​

Add a term to Quick Reference​

Create a new category​

Glossary Philosophy

Contribution Content Strategy

Add a new glossary term

Acronyms

Rules

Anchor Link Consistency

Updating Anchor Links

Troubleshooting Broken Anchor Links

Capitalization

Term Rules by Category

Headings

Definition and Purpose Fields

Related Terms Linking Strategy

Link Format

Linking Syntax

Source References

Format Guidelines

Best Practices

Voice and Tone

Active Voice

Avoid first-person pronouns

Purpose and Example Fields Exception

Clarity Over Rules

Add a term to Quick Reference

Create a new category