Architecting Information with Heading Hierarchies

In Lesson 1, you saw how structured text helps AI understand your intent. Now you'll learn the first building block of that structure: headings.

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.

• 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 (####): Deep technical details or exceptions

Example: A Simple Specification

Notice the pattern:

• One Level 1 heading for the title: # Task List App
• Four Level 2 headings for main sections: ## Problem, ## Features, and so on.

---

Concept 2: Following Proper Hierarchy

Headings must follow a logical hierarchy—you can't skip levels. You go from broad to specific.

Correct Hierarchy Example

Wrong Hierarchy Example (Don't Do This)

The fix: Always include Level 2 before Level 3.

---

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

You'll build this same Task Tracker App specification across Lessons 2-5.

Your Task for Lesson 2

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

Template to fill in:

---

Try With AI

Prompt 1: Structure Check

Prompt 2: Clarity Check

Prompt 3: Organization Feedback