Lists - Organizing Ideas
Imagine you're giving someone installation instructions in paragraph form:
"First install Python version 3.9 or higher, then download the project files, after that install the required packages using pip, and finally run the program."
Now imagine the same information as a numbered list:
- Install Python 3.9 or higher
- Download the project files
- Install required packages:
pip install requests- Run the program:
python app.py
The second version is instantly clearer. You can see at a glance that there are 4 steps, in a specific order.
Lists are essential in specifications because they help you present information clearly. When an AI agent reads a specification with proper lists, it immediately understands: "These are distinct items" or "These steps must happen in order."
This lesson teaches you two types of lists and when to use each.
Concept 1: Unordered Lists (Bullet Points)
Use unordered lists when you have items that don't need to be in any specific order. In markdown, create them with a dash (-) or asterisk (*) followed by a space.
Basic Syntax
- First item
- Second item
- Third item
Or with asterisks (same result):
* First item
* Second item
* Third item
Tip: Pick one style (dash or asterisk) and stick with it throughout your document.
When to Use Unordered Lists
Use bullet points when:
- Items have no specific sequence
- Order doesn't matter for understanding
- You're listing features, requirements, or options
- Items are independent of each other
Example: Feature List
Here's a feature list for a task tracker app:
# Task Tracker App
## Features
- Add tasks with title and description
- View all tasks with completion status
- Mark tasks as complete or incomplete
- Delete tasks you no longer need
- Save tasks to file (persist between sessions)
Why bullet points work here: Each feature is independent. Whether "Add tasks" comes before or after "Delete tasks" doesn't change what the app needs to do. The AI can implement these features in any order.
Concept 2: Ordered Lists (Numbered Steps)
Use ordered lists when items must be done in a specific sequence. In markdown, create them by typing 1. followed by a space.
Basic Syntax
1. First step
2. Second step
3. Third step
Note: Markdown is smart about numbering. Even if you type all 1., it will automatically number them 1, 2, 3. But it's clearer to number them correctly as you write.
When to Use Ordered Lists
Use numbered lists when:
- Steps must be done in sequence
- Order matters for correctness
- You're showing installation steps, procedures, or workflows
- Each step depends on the previous one
Example: Installation Steps
Here's installation instructions for a weather app:
# Weather Dashboard
## Installation
1. Install Python 3.9 or higher from python.org
2. Download the project files
3. Navigate to the project folder: `cd weather-dashboard`
4. Install required packages: `pip install requests`
5. Run the program: `python weather.py`
Why numbered steps work here: You must install Python before you can install packages. You must navigate to the folder before running the program. The sequence matters.
Example: Troubleshooting Steps
## Troubleshooting: "Module Not Found" Error
If you see this error, try these steps in order:
1. Check that Python 3.9+ is installed: `python --version`
2. Verify you're in the correct folder: `pwd` (Mac/Linux) or `cd` (Windows)
3. Reinstall packages: `pip install --upgrade requests`
4. If still failing, delete venv folder and recreate it
The sequence matters here too — you check Python first, then location, then reinstall, then venv.
Concept 3: Choosing the Right List Type
How do you know which type to use? Ask yourself: Does order matter?
Decision Guide
Use unordered lists (-) when:
- Describing features of an app
- Listing requirements or constraints
- Showing options or alternatives
- Items can be done in any order
Use ordered lists (1.) when:
- Showing installation instructions
- Describing a workflow or process
- Giving troubleshooting steps
- Sequence affects outcome
Examples Side by Side
Unordered (order doesn't matter):
## Features
- Dark mode support
- Export to PDF
- Auto-save every 5 minutes
- Keyboard shortcuts
These features are independent. Adding dark mode doesn't require export to PDF first.
Ordered (order matters):
## Setup Process
1. Create account
2. Verify email address
3. Set up profile
4. Start using the app
You must create an account before verifying email. You must verify email before setting up profile.
Practice Exercise: Task Tracker App (Part 2 - Lists)
Continuing from Lesson 2: Open the Task Tracker App specification you created in Lesson 2. You'll now add lists to organize features and installation steps.
Your Task for Lesson 3
Add two types of lists to your existing Task Tracker App structure:
Part 1: Add Feature Descriptions (Unordered Lists)
Under each Level 3 heading in the Features section, add bullet points describing what that feature does:
## Features
### Add Tasks
- Create tasks with title and description
- Set optional due dates
- Assign priority levels (high, medium, low)
### View Tasks
- Display all tasks with status
- Filter by priority or due date
- Show completed and pending separately
### Mark Complete
- Mark tasks as done
- Track completion timestamps
- Move completed tasks to archive
### Delete Tasks
- Remove tasks permanently
- Confirm before deleting to prevent accidents
Part 2: Add Installation Steps (Ordered List)
Fill in the Installation section with numbered steps:
## Installation
1. Install Python 3.9 or higher from python.org
2. Download the task tracker files from GitHub
3. Navigate to the project folder: `cd task-tracker`
4. Run the program: `python tracker.py`
Part 3: Add Problem Description
Under the Problem section, describe what problem this app solves (1-2 sentences as a paragraph, not a list).
Validation Checklist
Check your updated specification:
- Feature descriptions use unordered lists (
-) under each Level 3 heading - Installation uses ordered list (
1. 2. 3. 4.) - Each list item starts with dash/number + space
- Feature lists have no specific order (could be rearranged)
- Installation steps must be done in sequence
- Problem section is a paragraph (not a list)
Save this file! You'll add code blocks in Lesson 4.
Common Mistakes to Avoid
Mistake 1: Forgetting the Space
Wrong:
-No space after dash
1.No space after number
Correct:
- Space after dash
1. Space after number
Always put a space after the dash or number.
Mistake 2: Using Ordered Lists for Features
Wrong (features don't need order):
## Features
1. Dark mode
2. Export to PDF
3. Auto-save
Correct:
## Features
- Dark mode
- Export to PDF
- Auto-save
Features usually don't have a required order.
Mistake 3: Using Unordered Lists for Steps
Wrong (steps need order):
## Installation
- Install Python
- Run the program
- Install packages
Correct:
## Installation
1. Install Python
2. Install packages
3. Run the program
Installation steps must be in the right sequence.
Why This Matters for AI
When you use lists correctly in specifications, AI agents can:
- Identify distinct items — "This app has 5 features"
- Understand dependencies — "Step 2 requires Step 1 to complete first"
- Generate appropriate code — "Create 5 functions, one for each feature"
- Follow sequences — "Set up installation script with these 4 steps in order"
Good list usage makes your specifications clearer, which leads to better AI-generated code.
Try With AI
Validate your Task Tracker App lists with AI feedback.
Setup
Use ChatGPT web (or your AI companion from earlier chapters).
Exercise
Take your updated Task Tracker App specification (now with lists added) and ask ChatGPT to review it:
Prompt 1 (List Type Check):
I'm learning markdown lists. Can you check if I used the right list types?
Tell me if my features should be numbered or if my steps should be bullet points:
[Paste your specification here]
Prompt 2 (Clarity Check):
Can you identify:
1. How many features this app has
2. How many installation steps are required
3. Whether the steps must be done in order
Based on my lists?
Prompt 3 (Improvement Suggestion):
Based on my specification, what other lists could I add to make
this clearer? (Like requirements, error messages, or configuration steps)
Expected Outcomes
From Prompt 1: ChatGPT will confirm whether you chose the right list types (ordered vs unordered)
From Prompt 2: ChatGPT should be able to count items and understand sequence requirements from your list choices
From Prompt 3: ChatGPT will suggest additional lists to strengthen your specification
Your Task: Apply the Verification Framework
After ChatGPT responds, verify its feedback:
- Check against what you know: Look at your installation steps. Could you do step 3 before step 2? (If no, ordered list is correct)
- Ask for reasoning: "Why should features be unordered? Could they be reordered without breaking anything?"
- Test the claim: Try mentally rearranging your feature list. Does the app still make sense?
- Cross-reference: Look at real GitHub project READMEs. How do they organize features vs. installation steps?
Reflection
Write a brief reflection (3-5 sentences):
- When would you use bullet points vs numbered lists?
- Did the AI's feedback help you see where lists make specifications clearer?
- Can you think of a specification where you'd need both list types?
- Did manually checking list order (step 1 of verification) teach you something ChatGPT's approval alone wouldn't have?
Why Verification Matters Here
ChatGPT might say "your lists look good!" But if you:
- Manually test sequence: Can installation step 3 happen before step 1? (No → proves ordered list is right)
- Compare to real examples: GitHub READMEs consistently use unordered for features, ordered for installation (pattern recognition)
...you're learning the underlying logic, not just getting approval.
Save your Task Tracker App file — you'll add code blocks in Lesson 4!