Skip to main content

Headings - Creating Document Hierarchy

Imagine trying to find information in a document that's just one long wall of text. You'd scroll endlessly, hunting for the part you need. Now imagine that same document with clear sections: "Problem," "Solution," "Features," "Installation." Suddenly you can scan it in seconds.

In markdown, headings create this structure. They organize your document into sections that both humans and AI agents can quickly understand. When you write a specification, headings tell the AI: "This is the problem. These are the features. This is what the output should look like."

This lesson teaches you how to create clear document structure using headings.

Concept 1: Using Hash Symbols for Headings​

Markdown uses the hash symbol (#) to create headings. More hash symbols = smaller heading.

Here's how it works:

# Level 1 Heading (Largest)
## Level 2 Heading (Large)
### Level 3 Heading (Medium)
#### Level 4 Heading (Small)

What each level is for:

  • Level 1 (#): The document title (use once at the top)
  • Level 2 (##): Main sections (Problem, Features, Installation, etc.)
  • Level 3 (###): Subsections within a main section
  • Level 4 (####): Details within a subsection (rarely needed)

Example: A Simple Specification​

Here's a specification for a task list app:

# Task List App

## Problem
Users need a simple way to track daily tasks without complicated software.

## Features
- Add new tasks
- View all tasks
- Mark tasks as complete
- Delete old tasks

## Expected Output
When user views tasks, they should see:

1. Buy groceries [Complete]
2. Call dentist [Pending]
3. Submit report [Pending]

## Installation
Run this command to install:
pip install task-tracker

See the structure?

  • One Level 1 heading for the title: # Task List App
  • Four Level 2 headings for main sections: ## Problem, ## Features, etc.
  • No Level 3 headings needed (the document is simple enough)

This structure lets anyone (human or AI) scan the document and immediately understand what each section contains.

Concept 2: Following Proper Hierarchy​

Headings must follow a logical hierarchy — you can't skip levels.

Think of headings like organizing folders on your computer:

Main Folder (Level 1)
  ├── Documents Folder (Level 2)
  │   ├── Work Documents (Level 3)
  │   └── Personal Documents (Level 3)
  └── Photos Folder (Level 2)
      ├── Vacation Photos (Level 3)
      └── Family Photos (Level 3)

You go from broad to specific. You don't put "Vacation Photos" directly under "Main Folder" — it belongs under "Photos Folder" first.

Correct Hierarchy Example​

# Project Documentation

## Installation Guide
Instructions for setting up the project.

### Step 1: Install Dependencies
Run npm install to get started.

### Step 2: Configure Settings
Edit the config.json file.

## User Guide
How to use the application.

This is correct because:

  • Level 1 (#) is the overall title
  • Level 2 (##) sections divide the document
  • Level 3 (###) subsections provide details under each Level 2 section

Wrong Hierarchy Example (Don't Do This)​

# Project Documentation

### Step 1: Install Dependencies  ← WRONG! Skipped Level 2
This doesn't make sense without a parent section.

## Installation Guide  ← Now Level 2 appears after Level 3

This is wrong because:

  • We jumped from Level 1 directly to Level 3 (skipped Level 2)
  • The hierarchy is broken — readers don't know what "Step 1" belongs to

The fix: Always include Level 2 before Level 3:

# Project Documentation

## Installation Guide

### Step 1: Install Dependencies

Practice Exercise: Task Tracker App (Part 1 - Headings)​

Important: You'll build this same Task Tracker App specification across Lessons 2-5. Each lesson adds a new markdown element:

  • Lesson 2 (now): Add headings to create structure
  • Lesson 3: Add lists to organize features and steps
  • Lesson 4: Add code blocks to show expected output
  • Lesson 5: Add links, images, and emphasis to complete it

By Lesson 5, you'll have a complete specification that an AI agent can implement.

Your Task for Lesson 2​

Create the structure for a Task Tracker App specification using only headings.

Requirements:

  • Add a Level 1 title: # Task Tracker App
  • Include these Level 2 sections: ## Problem, ## Features, ## Expected Output, ## Installation
  • Under Features, add Level 3 headings: ### Add Tasks, ### View Tasks, ### Mark Complete, ### Delete Tasks

Template to fill in:

# Task Tracker App

## Problem
[In Lesson 3, you'll add a description here]

## Features

### Add Tasks
[Features will be described in Lesson 3]

### View Tasks
[Features will be described in Lesson 3]

### Mark Complete
[Features will be described in Lesson 3]

### Delete Tasks
[Features will be described in Lesson 3]

## Expected Output
[In Lesson 4, you'll add a code block showing what the app prints]

## Installation
[In Lesson 3, you'll add installation steps here]

For now: Just create the heading structure. Leave the sections empty (we'll fill them in later lessons).

Validation Checklist​

After you write your specification structure, check these:

  • Document has exactly ONE Level 1 heading (# Task Tracker App)
  • Four Level 2 headings (## Problem, ## Features, ## Expected Output, ## Installation)
  • Four Level 3 headings under ## Features (Add Tasks, View Tasks, Mark Complete, Delete Tasks)
  • No levels are skipped (Level 3 headings only appear under Level 2)
  • Each heading describes what its section will contain

Save this file! You'll continue building it in Lessons 3, 4, and 5.

Common Mistakes to Avoid​

Mistake 1: Forgetting the Space​

Wrong:

#Heading Without Space

Correct:

# Heading With Space

Always put a space after the hash symbols.

Mistake 2: Using Multiple Level 1 Headings​

Wrong:

# My App

# Problem
# Features

Correct:

# My App

## Problem
## Features

Use # only once for the document title. Use ## for main sections.

Mistake 3: Skipping Levels​

Wrong:

# My App
### Installation Steps  ← Skipped Level 2

Correct:

# My App
## Installation
### Installation Steps

Always include the intermediate level.

Why This Matters for AI​

When you write a specification with clear headings, AI agents can:

  1. Parse the structure — "This document has 4 main sections"
  2. Find specific information — "The features are in the Features section"
  3. Validate completeness — "Does this spec include a Problem section?"
  4. Generate better code — "The features list tells me what functions to create"

Good headings make your specifications easier for AI to understand, which means better code generation.

Try With AI​

Now let's validate your Task Tracker App heading structure with AI feedback.

Setup​

Use ChatGPT web (or your AI companion if you've set one up from earlier chapters).

Exercise​

Take the Task Tracker App specification structure you created above and ask ChatGPT to review it with these prompts:

Prompt 1 (Structure Check):

I'm learning markdown headings. Can you check if this specification
has correct heading hierarchy? Tell me if I skipped any levels or
used the wrong heading sizes:

[Paste your specification here]

Prompt 2 (Clarity Check):

Based on just my document headings (not the content), could you
build this project? What questions would you have? What additional
sections might be missing?

Prompt 3 (Organization Feedback):

If you were implementing this specification, would this heading
structure help you understand the requirements clearly? Why or why not?

Expected Outcomes​

From Prompt 1, you should get:

  • Confirmation that your hierarchy is logical (no skipped levels)
  • Feedback on whether headings are descriptive
  • Suggestions for clarity if any headings are vague

From Prompt 2, you should see:

  • Which sections are clear from headings alone
  • What sections might be missing (e.g., "Installation" if you forgot it)
  • Questions that reveal gaps in your specification

From Prompt 3, you should understand:

  • Whether your structure is implementable
  • How the AI agent reads and interprets document structure
  • Confirmation that clear hierarchy = clearer AI-generated code

Your Task: Apply the Verification Framework​

After the AI responds to all three prompts, verify its feedback using the framework from Lesson 1:

  1. Check against what you know: Manually count your heading levels. Did you skip any? Does AI's assessment match reality?
  2. Ask for reasoning: "Why do you say my structure is correct? What specific elements make it good?"
  3. Test the claim: Look at your headings only (no content). Can someone understand the spec structure from headings alone?
  4. Cross-reference: Compare your structure to a real GitHub README (search "task tracker" on GitHub and find examples)

Reflection​

Write a brief reflection (3-5 sentences) answering:

  • What was the most important thing you learned about heading hierarchy?
  • Did the AI's feedback change how you think about document structure?
  • How will you apply this to specifications you write in future lessons?
  • Did verifying AI's feedback (instead of just accepting it) help you learn more deeply? How?

Why Verification Matters Here​

If you accept AI feedback blindly, you're outsourcing your learning. But when you verify AI's assessment against:

  • The heading rules you learned
  • Real-world examples (GitHub READMEs)
  • Your own manual checking

...you're building judgment. That's the goal: not getting AI approval, but developing your own ability to recognize good document structure.

Save your Task Tracker App file — you'll add lists to it in Lesson 3!