Before I Write a README, I Want to Explain My Project Out Loud

I can spend an evening fixing a small interaction and still struggle to write three useful sentences about the project. The code is right there. The explanation somehow isn’t. For my next side project, I want to try a different starting point: record a short walkthrough, turn the narration into text, and edit that into documentation someone else can actually follow.

The Blank README Is an Awkward Place to Start

I Know Too Much About My Own Project

Once I’ve spent enough time building something, I stop noticing how much context it requires.

I know which file contains the sample data. I know why the first request takes longer. I also know that the button labelled “Reset” only clears the filters.

A new user knows none of this.

When I start writing documentation, though, those details often disappear. I describe the framework, list the features, and add a screenshot. Meanwhile, the person trying the project is wondering what they’re supposed to click first.

A Small Demo Gives Me Something Concrete to Explain

Rather than beginning with an introduction, I’d start with one task.

For a little expense tracker, that might mean importing a sample CSV and finding the total for a particular month. Nothing impressive. Just a complete action with a visible result.

I’d record the screen and explain what I’m doing as I go. If I catch myself saying, “You need to do this first because…,” I’d keep talking. That explanation probably belongs somewhere in the documentation.

I wouldn’t restart the recording because I paused or clicked the wrong tab. The recording is working material. Nobody needs a polished voice-over yet.

Turning a Walkthrough Into an Editable Draft

I Want the Words Without Typing Alongside the Demo

For this workflow, Audio Transcription provides a free way to turn a recording into editable text. It accepts audio and video uploads, as well as supported links.

That makes it a useful option for the messy first pass. I can explain the project while using it, then work with the resulting words afterward.

If I only need to think through a design choice, an audio recording would be enough. For a user-facing workflow, I’d keep the screen recording too. The narration and the interface tell different parts of the story.

The Transcript Is Material to Edit, Not a Finished README

Spoken explanations wander.

I might explain the import format, mention a future feature, then remember an important setup requirement halfway through clicking around. A transcript preserves that order, but a reader shouldn’t have to follow it.

I’d separate the useful material into setup, first successful action, expected result, and limitations. Then I’d rewrite it.

“Okay, so this bit here…” needs an actual name. A paragraph about something I might build next needs to leave the installation instructions. An assumption about the reader’s environment needs checking.

Here’s how I’d turn a few typical demo comments into documentation:

Getting words onto the page helps. Deciding which words belong there is still my job.

The Interesting Parts Are Usually Where I Hesitate

Every Unexplained Step Deserves a Second Look

Suppose I say, “Before running that, copy the example environment file.”

Was that step in the README? Does the example file exist in the repository? Are its variable names current?

This is where I think the exercise could be useful beyond writing. Explaining a workflow makes its hidden dependencies harder to ignore.

I’d also pay attention to instructions like “just select the right option.” If I can’t explain which option is right, the interface may need a clearer label—or the documentation may need an example.

Sometimes the next change should be a better error message rather than another paragraph.

I’d Check Technical Details Against the Project

A spoken command is easy to mishear. Package names, flags, paths, and version numbers deserve a separate check.

I wouldn’t copy a command from a transcript and assume it’s correct. I’d take the exact command from the project, run it in the environment I’m documenting, and compare the result with the instructions.

The same applies to claims. “This works offline” needs more support than me casually saying it during a demo.

I’d keep uncertain statements out of the finished documentation until I’ve verified them.

One Recording Could Support More Than the README

A Short Written Walkthrough Can Sit Beside the Video

For a narrated screen recording, a video to text converter can provide a transcript with timestamps, which helps when checking a passage against the original explanation.

I’d use that to prepare a short written walkthrough beside the video. Someone who only needs the setup command shouldn’t have to watch me navigate between windows to find it.

The tool also offers subtitle exports. If I decide to publish the demo, I can review the wording and timing before adding captions.

I’d still check what happens on screen. Transcribing “click here” doesn’t identify the button, and a silent stretch of coding won’t turn into a written explanation by itself.

An AI Summary Can Help Me Find a Starting Point

There’s also an AI summary feature, which I’d use with a narrow request:

Extract the setup requirements, demonstrated workflow, and limitations explicitly mentioned in this recording. Keep future ideas separate from existing features. Mark anything unclear instead of filling in the gaps.

I’d review that alongside the transcript, then decide what belongs in the README.

The distinction between existing features and future ideas matters to me. It’s easy to get enthusiastic while describing a side project. Documentation shouldn’t accidentally promise the thing I was merely considering.

I don’t expect this approach to write the whole README for me. I do expect it to give me something better than a blinking cursor: an explanation attached to a real task, with enough rough edges to show me what still needs work.

For the next project, that’s where I want to start. Open the app, try the first thing a new user would do, and explain it without skipping the inconvenient bits.