ctrlaltbrian.com

Practical how-tos for automation, GenAI, and the messy work of shipping.

Behind the Build

The README That Replaced a Sales Call

· 10 min read · #behind-the-build #tools #writing #automation

A real story about a 1-page README that did the selling for me, the 3 calls I stopped taking, and the 4 sections that made the README actually work.

The storyFor about 18 months I had a side project called "Transcribe," which is a small CLI that takes a meeting recording and returns a 3-paragraph summary. The project was open source, the project was on GitHub, and the project had a README. The README was the part that is the subject of this post.For the first 12 months, the README was 3 lines: project name, one-line description, install command. The 3-line README is the kind most side projects have, and the 3-line README is the kind that does not actually tell anyone what the project does. The 3-line README is the part I have seen 1,000 times, and the 3-line README is the part I am not proud of having written for 12 months.For the last 6 months, the README has been 1 page. The 1-page README is the part that changed everything. The 1-page README is the part that did the selling, the part that fielded the questions, the part that turned 3 sales calls a week into 0 sales calls a week. The 1-page README is the part I want to talk about.The 3 calls I stopped takingBefore the README rewrite, I was taking about 3 calls a week from people who had found the project on GitHub and wanted to know if it would work for their use case. The calls were the same shape every time:"So what does this do, exactly?" (3 minutes of me explaining what the README should have explained.)"Does it work with [specific tool]?" (3 minutes of me saying "probably, let me check.")"How much would it cost to get it working with [specific tool]?" (3 minutes of me giving a number.)"OK, send me a proposal." (2 minutes of "OK.")11 minutes per call, 3 calls a week, 33 minutes a week of my time. The 33 minutes is the part I was spending on calls I did not want to take, and the not-wanting is the part that made me rewrite the README. The not-wanting is also the part that the README rewrite solved.After the README rewrite, the calls dropped to about 1 every 2 weeks. The 1 every 2 weeks is the part that is the result I want to talk about, because the 1 every 2 weeks is the part that means the README is doing the selling for me, the README is the part that filters out the "this is not for you" cases, and the README is the part that lets the "this is for you" cases self-serve.The 4 sections that made the README workThe 1-page README has 4 sections. The 4 sections are not the 4 sections most READMEs have (the install command, the usage example, the contributing guide, the license). The 4 sections are the 4 sections that do the selling, and the selling is the part the README is built around.Section 1: "What this is and is not"The first section is 2 short paragraphs. The first paragraph says what the project does. The second paragraph says what the project does not do. The "does not do" is the part most READMEs skip, and the "does not do" is the part that does the most filtering. The "does not do" is the part that says "this is not for you if you need X, Y, or Z." The "does not do" is the part that turns a 30-minute call into a 5-second self-check.The actual section for Transcribe reads (paraphrased from memory):Transcribe is a CLI that takes a meeting recording and returns a 3-paragraph summary. Transcribe is not a transcription service (it does not return the full transcript). Transcribe is not real-time (you have to upload the recording after the meeting). Transcribe is not a Zoom plugin (it does not integrate with any video conferencing tool). If any of these are dealbreakers, this is not the right tool for you.The "not a Zoom plugin" line is the part that eliminated about 40% of the calls I was getting. The 40% is the part of the calls that was people who wanted exactly what Transcribe is not, and the not-is is the part I am proud of having written down. The not-is is the part that saved me 13 minutes a week.Section 2: "Who this is for"The second section is a list of 3 personas. The personas are the part that says "if you are one of these 3 people, this is for you." The 3 personas are the part that turns "is this for me?" into a 2-second self-check. The 3 personas are the part that does the segmenting, and the segmenting is the part I want to capture.The 3 personas for Transcribe were (paraphrased):You run 1-1 meetings and you want a summary you can paste into Notion.You run team retros and you want a summary you can paste into Slack.You do podcast post-production and you want show notes you can paste into your podcast host.The 3 personas are the part that catches the "I am exactly the right person for this" case. The "exactly the right person" case is the part that converts to a self-serve install, the "exactly the right person" case is the part that does not need a sales call, and the "exactly the right person" case is the part I want to optimize for.Section 3: "Try it in 60 seconds"The third section is a copy-pasteable 60-second demo. The 60-second demo is the part that takes the user from "I am interested" to "I have tried it" in 60 seconds. The 60-second demo is the part that does the actual selling, because the 60-second demo is the part that lets the user feel the product without me being involved.The 60-second demo for Transcribe was a 3-line bash block:

    brew install transcribe
    transcribe https://example.com/meeting.mp3
    cat summary.md

The 3 lines are the part that does the demo. The 3 lines are the part that does not require me. The 3 lines are the part that turns "I am interested" into "I have tried it and I have an opinion." The 3 lines are the part that I have learned to want, because the 3 lines are the part that makes the README a real README, and the real README is the part I want every project to have.Section 4: "When this is not enough"The fourth section is the part I almost skipped writing. The fourth section is "if you have tried Transcribe and it is not enough, here is what you should do next." The fourth section is the part that says "I am not the right tool for everyone, and if I am not, here is who is." The fourth section is the part that turns the "this is not for you" case into a graceful exit, and the graceful exit is the part that makes the user feel respected, and the respected is the part I want to optimize for.The actual section for Transcribe (paraphrased) said something like: "If you need full transcripts, try [tool]. If you need real-time transcription, try [tool]. If you need Zoom integration, try [tool]. If you need enterprise features (SSO, audit logs, etc.), this is not the right category of tool for you."The "is not the right category" is the part that respects the user's time. The "is not the right category" is the part that does not pretend to be something I am not. The "is not the right category" is the part that builds trust, and the trust is the part that makes the user come back when they have a problem Transcribe is the right tool for.What the README did not doIt did not close the deals. The README did the qualifying and the demo. The README did not close the deals. The deals still close on a call or in a DM. The deals are the part that requires a human, and the human is the part I want to be, not the part the README can be. The deals are the part I have learned to not try to automate.It did not replace the GitHub repo. The README links to the repo. The repo has the actual code. The README is the part that explains the code, not the part that contains the code. The README is the part that does the selling, and the selling is the part that is a different job from the code. The different job is the part I want to keep separate.It did not work for every project. The 1-page README is the right shape for a small, focused tool like Transcribe. The 1-page README is not the right shape for a library, a framework, or a complex platform. The library/framework/platform README needs a different structure (more technical detail, more API reference, more examples). The 1-page README is the right shape for the small-tool case, and the small-tool case is the part I want to talk about.What I would tell past-meIf I could go back and tell past-me one thing, it would be: write the README on day one. The 12 months of 3-line README were the 12 months of taking calls I did not want to take. The 12 months of calls were the 12 months I should have been writing the README. The README is the part I should have written on day one, and the day one is the part I did not. The day one is the part I would change.I would also tell past-me: the 4 sections are the parts that matter. The 4 sections are the part that turns a README into a sales doc. The 4 sections are the part that does the filtering, the demo, the segmenting, and the graceful exit. The 4 sections are the part I have used on every project since, and the 4 sections are the part I have learned to want. The 4 sections are the part that took 11 minutes per call off my week, and the 11 minutes per call is the part I would not trade for the 4 hours it took to write the 4 sections.Who this is forAnyone who has a side project and is taking calls they do not want to take. Anyone who has a tool and wants to scale the "I am interested" part of the funnel without scaling themselves. Anyone who has a README and is wondering why the README is not doing the selling. The 4 sections are the answer. The 4 sections are the part I want every README to have, and the every-README is the part I would love to see more of.The honest partThe "calls dropped from 3/week to 1 every 2 weeks" claim is real, but the claim is also not the whole story. The whole story is: the README did the qualifying, but the README also did some of the disqualifying. The disqualifying is the part that means some people who would have been a fit saw the README, decided it was not for them, and never reached out. The decided-not is the part I do not have a number on. The decided-not is the part I am fine with, because the decided-not is the part that respects the user's time, and the respecting is the part I have learned to want.The whole story also includes: the README is the part that made the project 5x more discoverable on GitHub. The 5x is the part I have not measured, but the 5x is the part I have observed in the GitHub star count and the "people who found me on GitHub" messages. The discoverable is the part the README is doing, and the doing is the part I am most proud of. The doing is the part I would not trade for the 4 hours of writing time.Want a README template that does the selling?The Blog Writing Factory includes a "README generator" prompt that takes a 1-paragraph description of your project and returns a 1-page README with the 4 sections above. The prompt is the part that turns a 4-hour writing session into a 30-minute writing session, and the 30-minute writing session is the part that makes the README worth writing.Buy on Gumroad. $14

Send me the rough edges if you try it. I read every message.