Week 11: Working Files: .md, .json, and .py

Learning objectives

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

1. Explain what a Markdown (.md) file is, and why AI tools and instruction documents often use it.
2. Read and write basic Markdown syntax, including headings, lists, bold and italic text, and links.
3. Explain what a JSON (.json) file is and how its structure of curly braces, square brackets, keys, and values works.
4. Read a JSON file's structure carefully with a screen reader, listening for punctuation rather than relying on visual indentation.
5. Explain basic Python (.py) syntax at a beginner level, including what a variable is and what a print statement does.
6. Open, read, and edit .md, .json, and .py files with a screen reader in both VS Code and Notepad.
7. Explain at least one practical reason a learner might want to use each of the three file types.
8. Decide, for a given task, whether Notepad's simplicity or VS Code's extra features is the better fit.

Lesson

This week goes deep into three file types you will keep meeting throughout the rest of this course, and very likely in AI-related work after it: Markdown files, JSON files, and Python files. Where do your words, and an AI tool's words, actually live? The answer is very often a file, specifically a plain text file with a particular structure. This lesson teaches what each file type actually is, why AI tools rely on it, and how to read and edit it comfortably and confidently with a screen reader, in two different editors: VS Code, a free code editor introduced from scratch later in this lesson, and Notepad, a simpler plain-text editor built into Windows. By the end of this lesson, these three file types should feel like familiar, ordinary text, not a mysterious wall of symbols.

Meeting VS Code for the First Time

Before working through the three file types in this lesson, it helps to have a comfortable editor ready, so this lesson starts with a quick, self-contained introduction to Visual Studio Code, usually just called VS Code, a free code editor made by Microsoft. A code editor is a program built for writing and organizing text files that a computer can run, such as small programs or configuration files. VS Code is one of the most widely used code editors in the world, and it has a screen reader mode and years of accessibility testing behind it, which is exactly why this lesson uses it.

The single most useful thing to learn about VS Code first is its command palette: a searchable list of essentially every command the application can perform. Opening the command palette is the one VS Code keystroke this course states as a reliable fact rather than something to explore for yourself, since it has stayed the same across many versions: Control plus Shift plus P (Command plus Shift plus P on a Mac). Once the command palette is open, type a few words describing what you want to do, such as "new file" or "save," arrow through the matching results with your screen reader, and press Enter to run the one you want. This turns "I don't know the menu path" into "I can search for what I need," which is the same reliable, search-based method worth using for any current feature in VS Code, since exact menu paths can shift from one update to the next in ways this course cannot promise to track. Control plus S saves whatever file is currently open, the same shortcut used across most Windows applications.

VS Code also has an integrated terminal: a text-based area, opened through the command palette, where you can type a command and immediately read its output with your screen reader. This matters most when you want to actually run a short program, such as one of the Python examples later in this lesson, and hear its output right away, rather than only reading the program's text. The command palette can open the integrated terminal the same way it opens or creates a file: search for a term such as "terminal," arrow to the matching result, and press Enter.

That is genuinely enough VS Code to get started. Everything else in this lesson builds on just these two habits: opening the command palette to find a command, and reading results with your screen reader the same way you read anything else in this course.

What Markdown Is, and Why It Matters for AI Work

Markdown is a way of writing a document using ordinary, plain text, plus a small number of simple symbols that mark structure, such as headings, lists, and bold text. A file written in Markdown is saved with the file extension .md. Unlike a word processor document, where you press a button or choose a menu item to make text bold or to turn a line into a heading, Markdown uses typed characters instead. A single number sign followed by a space at the start of a line, such as "# Notes," marks that line as a top-level heading. Two number signs, "## Notes," mark a slightly smaller, second-level heading, and so on. A hyphen followed by a space at the start of a line, such as "- milk," marks that line as one item in a bulleted list. Two asterisks on either side of a word or phrase, such as "**important**," mark that text as bold. A single asterisk on each side, such as "*important*," marks it as italic instead.

Why would anyone choose to type symbols like this instead of clicking a bold button? The answer connects directly to why AI tools use Markdown so often. Markdown is plain text, which means any program, on any device, can open it, read it, and understand its structure without needing special software built just for that one file format. An AI tool can read a Markdown file and immediately understand which lines are headings and which are list items, because the symbols themselves carry that information, right inside the text. This makes Markdown a natural fit for two very different, but closely related, jobs: writing documents meant for a human to read, and writing instructions meant for an AI tool to read.

You may already have a personal example of the second job in mind: a personal prompt library, a saved collection of prompts you reuse instead of rewriting from scratch. Many people keep exactly this kind of file in Markdown, using headings to organize prompts by category and bullet lists to note when each prompt works best. This idea can go even further into full instruction files, including one specific, well-known example called a CLAUDE.md file, a Markdown document that tells an AI tool your standing preferences and standards so you do not have to repeat them in every single conversation. Everything you practice with Markdown this week becomes direct, practical preparation for building files like that.

Markdown also has a genuine, specific accessibility advantage worth naming clearly. A complex word processor document can bury its structure inside visual formatting that a screen reader has to interpret and translate into speech: a heading might only be signaled by a slightly larger font size, and a bullet list might rely on an indent a sighted reader notices at a glance but a screen reader has to work to detect and announce correctly. A Markdown file has no hidden visual formatting to interpret at all. Its structure is spelled out directly in the text itself, as ordinary characters your screen reader already knows how to read perfectly. A number sign is a number sign. A hyphen is a hyphen. There is nothing hidden, and nothing left for a screen reader to guess at or approximate. This is exactly why so many technical documents, instruction files, and README files, the short documents that explain a piece of software, are written in Markdown: it is friendly to every reader, human and AI alike, and it is particularly friendly to a screen reader user, since there is no gap between what the file contains and what gets announced.

A Practical Walkthrough: Reading and Writing Basic Markdown Syntax

The best way to get comfortable with Markdown is to practice the handful of symbols that cover almost everything you will need. This section walks through each one with an example you can type yourself.

A heading starts with one or more number signs, followed by a space, followed by the heading text. One number sign makes the largest, top-level heading; two make a smaller, second-level heading; three make a smaller heading still. For example, typing:

# My Notes
## Today's Tasks

creates a top-level heading reading "My Notes" and, below it, a second-level heading reading "Today's Tasks." When you read a plain Markdown file with your screen reader, before it is turned into a formatted page by some other program, you will hear the number signs themselves spoken aloud, since a plain Markdown file is just text; a program specifically built to display Markdown as a formatted page, sometimes called a Markdown viewer or renderer, is what turns those symbols into an actual, styled heading. Either way, whether you are reading the raw symbols or a rendered version, the heading structure is unambiguous, because it comes directly from the text.

A bulleted list uses a hyphen and a space at the start of each line. For example:

- Milk
- Bread
- Eggs

creates a three-item list. A numbered list works similarly, using a number, a period, and a space, such as "1. First step," "2. Second step," and so on.

Bold and italic text use asterisks. Two asterisks on each side of a word or phrase makes it bold, such as "**important**." One asterisk on each side makes it italic, such as "*optional*." It can help to say the pattern out loud as you type it: "asterisk, asterisk, the word, asterisk, asterisk" for bold, and "asterisk, the word, asterisk" for italic. Saying it this way while you type builds the same kind of muscle memory you already use for other consistent keyboard patterns in this course.

A link uses a specific combination of square brackets and parentheses: square brackets around the text you want a reader to see, immediately followed by parentheses around the actual web address. For example: "[Claude's website](https://claude.ai)" creates a link where the visible text reads "Claude's website," and selecting it, in a program that renders Markdown, takes you to the address inside the parentheses. When you read this pattern with your screen reader in its raw, plain-text form, you will hear the square brackets, the link text, and the parentheses with the address, all read aloud in order, which sounds a little unusual the first few times but becomes easy to parse once you know the pattern to expect.

Try typing a short practice file now, using a plain text editor, either VS Code or Notepad, both covered in detail later in this lesson. Start with a top-level heading naming the file, add a short paragraph of ordinary text below it, add a bulleted list of two or three items, and make one word in your paragraph bold using the double-asterisk pattern. Save the file with a name ending in .md. Then close it, reopen it, and read it back with Say All, or your screen reader's continuous reading command, for reading a full document from the current position. If every symbol you typed is exactly where you expect it, you have written valid, working Markdown.

What JSON Is, and Why AI Tools and Configuration Files Use It

JSON, short for JavaScript Object Notation, is a plain-text way of storing structured data: information organized into clearly labeled pieces, rather than a single block of free-flowing prose. A file written in this format is saved with the extension .json. Where Markdown is built for documents meant to be read as continuous text, JSON is built for data meant to be looked up, organized, and processed by a program, though a person, with a little practice, can read it too.

JSON's structure rests on a small number of building blocks. Curly braces, an opening brace and a closing brace, mark the beginning and end of an object, a collection of related pieces of information. Inside those braces, each piece of information is written as a key and a value, separated by a colon: the key is a quoted label describing what the information is, and the value is the actual information itself. Commas separate one key-value pair from the next. Square brackets mark a list of items, called an array, when a value needs to hold more than one thing.

Here is a simple, fully explained example, the kind of small settings file you might build in this week's exercises:

{
  "name": "Mike",
  "theme": "dark",
  "notifications": true
}

Reading this left to right: an opening curly brace starts the object. The first key, in quotes, is "name," followed by a colon, followed by its value, in quotes, "Mike." A comma separates this pair from the next. The second key is "theme," with the value "dark." Another comma, then the third key, "notifications," with the value true, written without quotation marks because true and false are special JSON values representing a yes-or-no setting, rather than ordinary text. A closing curly brace ends the object. This tiny file might represent a real settings file for an application: who is using it, which color theme they prefer, and whether notifications are turned on.

Why do AI tools and configuration files, the files that store an application's settings, rely on JSON so heavily? Precision and structure. A program reading a JSON file does not have to guess where one piece of information ends and the next begins, the way it might have to guess with a loosely formatted paragraph of prose; the punctuation marks the boundaries exactly, every time, in the same predictable pattern. This same precision is exactly why many AI tools accept or return data in JSON format when a task calls for structured information rather than a plain written answer, such as a list of extracted names and dates, or a set of configuration options for how an AI feature should behave. Learning to read JSON, then, is not just about editing one small settings file for a class exercise; it is a skill that shows up any time you look under the hood of how a modern AI tool or piece of software actually stores what it knows.

Reading JSON's Structure With a Screen Reader

JSON has one feature that trips up new screen reader users more than any other: indentation. When a sighted person looks at a JSON file, extra spaces at the start of each line, used purely to make nested structure easier to see visually, instantly show which pieces of information belong inside which object or list, simply by how far each line is indented from the left edge. Most screen readers, by default, do not announce that visual indentation the way a sighted reader perceives it; some may announce a certain number of spaces if you listen very closely line by line, but that is a slow, unreliable way to understand a file's structure, and it is easy to lose track of exactly how many levels deep you are.

The reliable strategy is different: listen for punctuation instead of indentation. Every meaningful boundary in a JSON file is marked by a specific character, not by spacing, and your screen reader reads every one of those characters accurately if you are listening for them. An opening curly brace means "a new object is starting here." A closing curly brace means "that object just ended." A colon means "the key just spoken is now followed by its value." A comma means "one piece of information just ended, and another is about to begin." If you keep a mental count of how many opening braces you have heard without a matching closing brace yet, you always know how many levels deep you currently are, exactly the same information a sighted reader gets from counting indentation with their eyes, just gathered a different way, through your ears instead.

One more tool is worth checking for specifically: some code editors, including VS Code, can announce or highlight matching brackets, meaning that when your cursor sits on an opening brace, the editor can tell you, or visually show, exactly which closing brace pairs with it, even across a long file. Whether this feature is currently available, and exactly how it is triggered, is the kind of detail worth checking for yourself using VS Code's command palette, the same reliable, search-based method described earlier in this lesson, searching a term like "bracket" and reading through the results, rather than this course claiming one fixed keyboard shortcut that could change in a future update.

Reading JSON with a screen reader takes more patience than reading an ordinary paragraph, especially the first few times. That patience pays off quickly. Once you have deliberately read through a handful of JSON files, listening closely for braces, brackets, colons, and commas, your ear starts to catch the pattern automatically, the same way any repeated skill in this course becomes more automatic with practice, from Say All to the command palette you just learned earlier in this lesson.

Python Basics for Automation: A First Taste

Python is a widely used programming language, meaning a language for writing precise, step-by-step instructions a computer can carry out. It is especially well known for being relatively easy to read, even for people with no programming background, because it favors plain, clear commands over dense, cryptic symbols. A file containing Python instructions is saved with the extension .py. Python is used across an enormous range of work, from building entire applications to, most relevant for this course, writing small automation scripts: short programs that carry out a repetitive task automatically instead of a person doing it by hand every time, connecting directly back to the automation skill area this course builds toward.

This lesson is not a full programming course, and it does not try to be. Think of this section as a first taste, a small, safe amount of exposure to what Python actually looks and sounds like, enough to recognize it, read a short example with confidence, and make a tiny, deliberate edit, the same kind of first hands-on exposure this lesson already gave you to VS Code's screen reader mode earlier on. Full, structured programming instruction is not a goal of this course; using AI tools to help you write and understand small scripts, a skill later coursework builds on directly when you learn to build a simple agent, is.

Two ideas matter most at this beginner level. The first is a variable: a named place to store a value, so a program can refer back to that value later using a short, memorable name instead of retyping the whole value every time. Think of a variable the way you might think of a labeled folder: you put something inside it, name the folder something meaningful, and can pull the same thing back out later just by using its name. In Python, creating a variable looks like this:

name = "Mike"

Reading this left to right: "name" is the variable, the equals sign assigns a value to it, and "Mike" in quotation marks is that value, a short piece of text. From this point forward in the same script, typing "name" refers back to that stored value, "Mike," without retyping it.

The second idea is a print statement: an instruction that displays a message, or the value stored in a variable, as output when the script runs. A very short, complete Python script might contain exactly one line:

print("Hello, Mike!")

Reading this aloud: the word "print," followed by an opening parenthesis, followed by the message in quotation marks, followed by a closing parenthesis. Running this one-line script produces exactly one thing: the text "Hello, Mike!" appears as output. A slightly longer example combines both ideas:

name = "Mike"
print("Hello, " + name)

Here, the first line stores the text "Mike" in a variable named "name." The second line prints the phrase "Hello, " combined with whatever value is stored in "name," producing the same output, "Hello, Mike," but built from a reusable variable instead of a fixed, typed-out phrase. This small pattern, storing a value once and reusing it, is the same underlying idea behind much larger, more useful automation scripts you will encounter later in this course.

You do not need to understand every detail of how Python works to get real value from it right now. Even at this beginner level, being able to open a short Python file, recognize a variable and a print statement, and make a small, careful edit, gives you a genuine head start toward building a simple agent later in this course that uses exactly these building blocks, and others like them, to perform a repetitive task end to end.

Reading and Editing All Three File Types in VS Code and in Notepad

Earlier in this lesson you learned to open, read, and edit files inside VS Code, using the command palette, Control plus Shift plus P, to find commands like creating a new file, and Control plus S to save. Everything from that introduction still applies and still works exactly the same way for the deeper practice in this week's exercises: open the command palette, search for what you need, arrow through and read the results with your screen reader, and choose the command that matches your goal. If you are ever unsure of an exact current menu path for opening or creating a file, the command palette remains the single most reliable tool to fall back on.

This week adds a second environment: Notepad, a very simple, plain-text-only editor that comes built into every copy of Windows. Notepad has no syntax highlighting, no command palette, and no extensions; it opens a file, shows you its text, and lets you edit and save it, and nothing more. That simplicity is exactly its strength for certain tasks. Notepad's keyboard shortcuts have stayed essentially unchanged for decades, which means this course can state them as reliable fact, unlike a specific application's menu structure, which can shift from one update to the next the way VS Code's own menus can. Control plus N opens a new, empty file. Control plus O opens an existing file. Control plus S saves the current file. Once a file is open, Control plus Home moves your cursor instantly to the very beginning of the file, and Control plus End moves it instantly to the very end, both useful for quickly checking a file's overall length or jumping to add a new line at the bottom. Arrow keys move line by line and character by character exactly as you would expect, and Say All, or your screen reader's continuous reading command, reads the whole open file aloud from your current position, exactly as it does everywhere else in this course. Screen reader users on a Mac generally do not have Notepad available, since it is a Windows-only application, but the same idea, a very simple plain-text editor, is available through Mac's built-in TextEdit application, used in plain-text mode.

All three file types, Markdown, JSON, and Python, are ordinary plain text underneath, which means Notepad can open, read, and edit every single one of them just as easily as VS Code can, since Notepad does not care what a file's extension means; it simply shows you the text inside. Try this for yourself: open a .md file in Notepad using Control plus O, read it with Say All, add a new line at the end using Control plus End followed by Enter, and save it with Control plus S. The experience will feel noticeably plainer than VS Code, with none of the extra commands or panels, and for many quick tasks, that plainness is exactly what you want.

Notepad or VS Code? Choosing the Right Tool for the Job

With two capable editors now in your toolkit, it helps to know when each one is worth reaching for. Notepad is worth choosing when a task is quick and simple: jotting a short note, making a one-line edit to a JSON file, or writing a short Python script with a single print statement, especially when you want to get in, make the change, and get back out with the fewest possible keystrokes and the least possible complexity. Its lack of extra features is not a weakness in these moments; it is exactly why it opens instantly and never gets in your way.

VS Code earns its extra complexity when a task benefits from its extra features. Syntax highlighting, visual color-coding that marks different parts of a file's structure, such as a JSON key versus its value, or a Python keyword versus a variable name, is read out loud by some screen reader configurations as a spoken category, such as "string" or "keyword," which can help you double check that a file is structured the way you intend, especially in a longer or more complex file where listening for punctuation alone takes real concentration. VS Code's integrated terminal, introduced earlier in this lesson, matters most when you want to actually run a Python script and hear its output immediately, rather than only reading the script's text. The command palette matters most when you are not sure what a current feature is called or where to find it, since it turns "I don't know the menu path" into "I can search for what I need," a habit worth keeping for any complex application you meet after this course ends, not only VS Code.

A reasonable habit going forward: start with Notepad for anything quick and simple, and reach for VS Code when a task is longer, needs to be run rather than only read, or benefits from the extra structure VS Code can show and, in some configurations, read aloud.

Key terms from this week

Use this list to review the vocabulary introduced in this lesson before you start the exercises and the test.

Markdown

A way of writing a plain text document using simple typed symbols, such as a number sign or a hyphen, to mark structure like headings and lists.

JSON

Short for JavaScript Object Notation; a plain-text format for structured data, using curly braces, square brackets, keys, and values.

Python

A widely used, relatively easy-to-read programming language, often used for automation scripts.

Variable

A named place to store a value in a program, so the value can be reused later by name instead of being retyped.

Key-value pair

One piece of information in a JSON object: a quoted label, the key, followed by a colon and its value.

Print statement

A Python instruction that displays a message or a variable's value as output when a script runs.

Keyboard-only exercises

These exercises use only your keyboard. Screen reader commands are described in general terms below; substitute your own screen reader's equivalent command where needed.

Exercise 1: Create a small Markdown file in Notepad

1. Open Notepad. On a Mac, use TextEdit in plain-text mode as a substitute, since Notepad is Windows-only.
2. Create a new file with Control plus N.
3. Type a top-level heading using a number sign and a space, such as "# My Practice File," then press Enter.
4. Type a bulleted list of two or three items, each starting with a hyphen and a space, such as "- First item," pressing Enter after each one.
5. Save the file with Control plus S, giving it a name ending in .md, such as practice.md.
6. Close Notepad, reopen the file with Control plus O, and read it back with Say All, or your screen reader's continuous reading command, confirming the heading symbol and each list item saved correctly.

Exercise 2: Read a JSON file's structure carefully in VS Code

1. Open VS Code and open the command palette with Control plus Shift plus P (Command plus Shift plus P on a Mac).
2. Search for the command to create a new file, and save it with a name ending in .json, such as settings.json.
3. Type a small JSON object with two or three key-value pairs, following the pattern from this week's lesson: an opening curly brace, a quoted key, a colon, a quoted or unquoted value, a comma between pairs, and a closing curly brace.
4. Save the file with Control plus S, then arrow through it slowly, character by character if needed, listening specifically for each brace, colon, and comma rather than trying to judge indentation.
5. Use VS Code's command palette to search for a term such as "bracket," to check whether a matching-bracket command is currently available in your version.

Exercise 3: Create, read, and run a short Python file in VS Code

1. In VS Code, open the command palette with Control plus Shift plus P and create a new file, saving it with a name ending in .py, such as hello.py.
2. Type one line following this week's example: a variable assignment, such as name = "Mike", then press Enter and type a print statement, such as print("Hello, " + name).
3. Save the file with Control plus S, then read it back with Say All, or your screen reader's continuous reading command, confirming both lines are exactly as you typed them.
4. If you are comfortable doing so, open the integrated terminal, introduced earlier in this lesson, through the command palette, run the file, and listen to the output with Say All. If you would rather not run it yet, that is fine; reading the file back accurately is the required part of this exercise.

Portfolio project: My AI Working Files

This week's portfolio piece starts a working-files folder you will keep expanding for the rest of this course, beginning with the three file types from this week's lesson, each one created and verified readable with your screen reader.

1. Create a new folder for this project, such as ai-working-files, using either VS Code or Notepad.
2. Add a Markdown file, such as personal-notes.md, containing at least two headings and one bulleted list, using the syntax from this week's lesson.
3. Add a JSON file, such as contact-info.json, containing at least three key-value pairs, such as a name, an email address, and a favorite AI tool, following the exact curly-brace and colon pattern from this week's lesson.
4. Add a short Python file, such as greeting.py, containing at least one variable and one print statement, following this week's example.
5. Save all three files, then close and reopen each one, reading it with Say All to confirm every symbol and every value is exactly what you intended.
6. Keep this folder in your portfolio. You will build on it directly in future coursework when you create your first instruction file.

Weekly test

Answer key

Each answer below includes a one-sentence explanation drawn from this week's lesson.