Creating Your Own Style Guide — Build Documentation Standards for Your Project

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

Creating your own style guide does not mean starting from scratch. The best style guides combine rules from existing guides with project-specific additions. This lesson walks through the process of creating a style guide for your project.

In this lesson, you will learn how to create a custom style guide that serves your writers and improves your documentation consistency.

What You'll Learn

You will adapt existing style guides for your project, add project-specific rules, format the guide for usability, and configure automated enforcement.

Why It Matters

A custom style guide tailored to your project beats a generic guide. Writers follow rules that address their actual needs.

Real-World Use

DodaTech created a 15-page custom style guide based on Google Developer Style Guide with 30 project-specific terminology entries and Vale configurations for automated enforcement.

flowchart TD
  A[Create Style Guide] --> B[Choose Base Guide]
  A --> C[Add Project Rules]
  A --> D[Format for Usability]
  A --> E[Automate Enforcement]
  B --> F[Google or Microsoft]
  C --> G[Product Names, Terms]
  D --> H[Examples, Quick Ref]
  E --> I[Vale Configuration]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Steps to Create a Style Guide

Choose a base guide that matches your content type. Google Developer Style Guide for developer documentation. Microsoft Style Guide for accessibility focus. Apple Style Guide for consumer-facing content.

Add project-specific rules: product names with correct capitalization, technical terminology, API naming conventions, and brand voice guidelines.

Write rules with examples. Every rule needs a good example and a bad example. Writers need to see what Compliance looks like.

Organize the guide for quick reference. Group related rules. Create a quick-reference card for the top 10 rules.

# DodaTech Custom Style Guide - Sample Rules

## Product Names
- DodaZIP (all caps ZIP)
- Doda Browser (capital B)
- Durga Antivirus Pro (all capitalized)

## API Terminology
- Use API key not token for authentication
- Use endpoint not route for URLs
- Use request body not payload

Automated Enforcement

Configure Vale to check for your custom rules. Create terminology substitution rules, capitalization checks, and formatting rules.

Store Vale configuration in your documentation Repository. Run it in CI to enforce rules on every Pull Request.

Create custom Vale rules for project-specific requirements. Vale's YAML format makes it easy to add new rules.

# Vale rule for DodaTech product names
extends: substitution
message: Use '%s' instead of '%s'.
level: error
swap:
  "(?i)dodazip|doda.zip": DodaZIP
  "(?i)doda browser|dodabrowser": Doda Browser
  "(?i)durga antivirus": Durga Antivirus Pro

Common Mistakes

1. Starting From Scratch

Creating a complete original guide. Start with an existing guide and adapt it.

2. Too Many Rules

A 100-page guide that nobody reads. Keep it focused on rules that matter.

3. No Examples

Rules without examples require interpretation. Provide good and bad examples.

4. No Automation

A style guide without automated enforcement depends on human vigilance.

5. Ignoring Writer Feedback

Rules that writers find unhelpful or contradictory. Collect feedback and revise.

6. Never Updated

A style guide that stays static while products evolve. Review and update annually.

7. Hard to Find

A style guide stored where writers cannot easily access it. Keep it in the repository.

Practice Questions

1. What should you start with when creating a style guide?

An existing guide like Google or Microsoft. Adapt it rather than starting from scratch.

2. What project-specific rules should you add?

Product names, technical terminology, API naming conventions, and brand voice guidelines.

3. Why include examples with every rule?

Examples clarify the rule. Writers can see exactly what compliance looks like.

4. How do you enforce style rules automatically?

Use Vale with custom rules. Run it in CI to check every pull request.

5. Challenge: Create a custom style guide for a project you know. Include an adapted base guide, 15 project-specific rules, and Vale configuration for automated enforcement.

FAQ

Mini Project

Create a complete custom style guide for a project. Choose a base guide, add 20 project-specific rules with examples, organize the guide for quick reference, create Vale configuration, and test it on existing content.

What's Next

Next: Style Guide Capstone Project