Training Builder Style Guide

Version 3.5 | A comprehensive guide for creating consistent, professional curricular content. Synthesizes best practices from Google, Gruntwork, Ciro Santilli, and GitHub markdown guides.

Document Structure

File Header

Every document should begin with a clear header:

# Document Title

**Chapter X:** Chapter Title
**Generated:** YYYY-MM-DD
**Component:** Book Chapter | Exercise | Quiz | etc.

---

Section Organization

Start with learning objectives or overview
Progress from foundational to advanced concepts
End with summary, key takeaways, or next steps
Include estimated reading/completion time

Headings

Capitalization Rules

Level	Style	Example
H1	Title Case	# Introduction to Full-Stack Development
H2	Title Case	## Getting Started with React
H3+	Sentence case	### Setting up your environment

Title Case (APA Style): Capitalize first/last word, major words (nouns, verbs, adjectives), and words 4+ letters. Lowercase articles (a, an, the), short prepositions (in, on, at), and conjunctions (and, but, or).

Text Formatting

Purpose	Format	Example
Strong emphasis	bold	important
Mild emphasis	italic	technical term
UI elements	bold	Click Save
File names	`code`	`package.json`
Commands	`code`	`npm start`

Lists

Bullet Points

Use hyphens (-) not asterisks (*)
One space after the marker
Capitalize first word
No period for short items

Numbered Lists

Use 1. for all items (auto-increments)
Reserve for sequential items
Indent with 2 or 4 spaces

Code

Always specify the language for code blocks:

```javascript
import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}
```

Best Practices

Keep examples focused - show one concept at a time
Use meaningful names - calculateTotal not calc
Add comments - explain non-obvious logic
Show complete examples - include imports and context

Admonitions

Use GitHub-flavored markdown admonitions for callouts:

Note

Useful information that users should know, even when skimming content.

> [!NOTE]

Tip

Helpful advice for doing things better or more easily.

> [!TIP]

Important

Key information users need to know to achieve their goal.

> [!IMPORTANT]

Warning

Urgent info that needs immediate user attention to avoid problems.

> [!WARNING]

Caution

Advises about risks or negative outcomes of certain actions.

> [!CAUTION]

Curricular Elements

Learning Objectives

## Learning Objectives

By the end of this chapter, you will be able to:

- Explain the principles of RESTful API design
- Implement CRUD operations using Express.js
- Handle errors and validate input data
- Document APIs using OpenAPI/Swagger

Exercise Structure

## Exercise 3.1: Building a REST API

**Objective**: Create a basic CRUD API for a todo list.

**Time**: 30 minutes

**Instructions**:

1. Create a new Express.js project
2. Implement the following endpoints...

**Success Criteria**:
- [ ] All endpoints return appropriate status codes
- [ ] Data persists between requests

Quick Reference

Element	Style
H1/H2	Title Case
H3+	Sentence case
Bullets	Hyphens (-)
Code blocks	Always specify language
Emphasis	bold / italic
Notes	> [!NOTE]
File names	`filename.ext`
Commands	`command --flag`

Maintained by: Training Builder Team

References: Google Style Guide, Gruntwork Guide, Ciro Santilli Guide, GitHub Docs

View Credits and Licenses →