I find it surprising/annoying/frustrating that many README's start of with how to download/install the software, without ever telling you what it is designed to do. (Perhaps you must have some inkling of what it does to be motivated to read the README.)

> But it is really hard to ignore your own biases. Of course you know that certain commands require sudo and obviously when you wrote -foo you meant --foo and everyone knows that you have to reboot afterwards.

I sometimes write readmes for myself, so that I can remember the exact steps to generate a data report, etc.

It's surprising how much they become incomprehensible after just a couple of weeks; when everything's in our head it's all clear, fluid and self-explanatory; but once we have forgotten the context, nothing makes sense anymore.

>I hadn't actually explained what the software would do.

Half the posts I see lately are like, "Gleam 2.0. What we learned" and then you go to the homepage and it's "Gleam is a Tribble for your Fork! (Scroll down) See if you qualify for Gleam Enterprise!"

This is very close to what you call usability testing in the field of UX design.

The Nielson Norman Group has a good introduction to this: https://www.nngroup.com/articles/usability-testing-101/

Is this interesting to people on HN?

I majored in a mix between coding and design.

> I hadn't actually explained what the software would do.

I cannot tell you how many READMEs I've read that follow the pattern: "<uninformative-name> is a <buzzword> <buzzword> written in <language>." I only have some semblance of what it does after using/seeing a demo; too often one that isnt available through the README.

I love this. Most readmes are plain bad. I think the most egregious is when a readme doesn't state what the project does. I get that not every project is aimed at the public, but if you go through the bother of creating a readme file, why not go the extra 10 centimeters by writing the most basic information? Other issues: * outdated (and thereby wrong) information * using un-introduced abbreviations (bonus points for abbreviations that have common meanings, e.g.: EG, NB, IE, ETC)

IDEO.org's design kit has a lot of helpful "design research" tools to solicit person-to-person feedback. Perhaps helpful to people reading this https://www.designkit.org/methods/interview.html

This used to be called "I hired QA people to identify gaps in my project", but hey now it has become paying people to follow readme

Humans are great, but AI can really help here too. Let me explain :)

I write docs that AI agents have to follow to play a game through an API, then spin up 20 sub-agents each with their own identities / properties etc. and watch where they fail. They get stuck in the same places as humans.. or they will point out the "obvious" steps not explicitly mentioned.

now where the AI tests start to fall apart is that an agent doesn’t tell you the doc is confusing, it just does something wrong with full confidence. A person on a call says “wait, what?” and that’s worth the 25 euros :)

> My jokes aren't funny and are actively confusing.

I used to write technical documents in prose style, sometimes with meandering stories. I guess I picked it up from my early blogging days. I realized I hated reading some of them back. So I tried to keep it cut and dried. I do sometimes sprinkle a bit of colorful wording just to add a bit of humanity but only if it doesn't get in the way of the main message.

There's a zeroth step missing from both the Quickstart and Full Set Up: install php-fpm, configure it, and configure your http server to serve using it as a backend.

It seems to be taken for granted — that's something you'd already have in place if you're already serving applications in PHP, but would have to figure out on your own if you haven't served anything in PHP so far in your life.

Most README files should include a screenshot.

Even if it is a command-line tool, a screenshot helps provide a better understanding of what to expect.

Most documentation reads like you should already know what you’re doing, which makes sense because it was written by someone who already knows how to do the process.

I think good technical writing requires the same skills as good product ownership, that is empathy for the user and their perspective. Often technical writing is an after thought and not someone’s whole role and it really shows.

Good article

I know there are some great README's (and other documents) around, that document best-practices or templates for great README's. I found one that looked very useful and would've sworn I starred the repo to find it again in time of need. Alas, can't find it. Anyone has some good resources to point to, to add to this thread?

Update: Found some related HN threads (omitted link-rotted submissions).

- I'd like to review your README https://news.ycombinator.com/item?id=26842191 (91 comments)

- Readme.so – Easiest Way to Create a Readme https://news.ycombinator.com/item?id=27006740 (65 comments)

- Readme Driven Development https://news.ycombinator.com/item?id=1627246 (57 comments)

Documentation is so important. I have been treating documentation in the same way I handle code. I found mkdocs works pretty well and integrated with a github job that updates the docs when I commit changes to my main branch. It also allows contributors to correct errors or add helpful instructions to documents. I think I have not paid enough attention to my biases though and like the idea of hiring someone to go through the process. I think my instructions are sound but maybe not so much for a user who is not as familiar as I am. I may not be doing things the optimal way but I have used a lot of documentation over the years and feel what I have done addresses gripes I have had with "Big Tech" provided docs.

To a certain extent, you can think of writing documentation like writing code. Leverage your coding skills to improve your explanatory writing.

Each phrase or sentence is an operation that changes the state. The state is the mind of the reader. For it to work, you have to understand the starting state, and then construct a valid sequence that modifies the state step by step until it reaches the desired state. Every step has preconditions and postconditions. You can't leave important values uninitialized. You can't refer to symbols that haven't been defined. You can't just sit down and blurt out whatever comes to mind; you have to "play computer" (or "play reader") in your head to model the effects of what you're writing. You need to be aware of which "platform" you're targeting (developers, users) and understand quirks of each variation of that platform. Some of your operations might fail, and you may need a way to detect and/or recover.

Obviously don't take it too far and reduce writing to this. But I think it's helpful for getting into a mindset where you are thinking about communication in an end-to-end, closed-loop way. Your mind needs to be engaged and stay engaged with the question of what the experience is like for the reader. It's very easy to default to an open-loop mode where you just have a random string of thoughts about the subject, let your brain translate them into words, write that down, and call it done. There's a big difference between expressing thoughts and communicating ideas effectively.

Thinking about it this way could also maybe help with motivation. It's satisfying to write computer code and really nail it and have it do its job effectively, right? You can get a similar feeling of satisfaction from good writing.

When I was testing my books' instructions, I would operate from a fresh state and only allow copy paste. Every single command and line of code had to be expressed and in the correct order.

This was generally really a good way to go about it, because it requires everything to be correct with no room for adjustment.

Still people would miss things, but it always came from skipping instructions (sometimes completely.) Maybe 10 support inquiries total.

> My jokes aren't funny and are actively confusing.

2real4me

In all seriousness tho, I don't really put jokes in readmes or code comments. Jokes should be tied to a moment where they make sense, not just be present in perpetuum. Slack is great for jokes, or maybe even a notion design doc comment, alongside the actual feedback.

But sticking jokes in your readme just feels like "I have you here for other reasons, now you have to listen to me be funny".

We most times forget that not everyone can read our minds or see exactly what we see in our systems. When it comes to communicating ideas, there's always the requirement to actually communicate what it is the readers needs to know.

I oftentimes find myself spending more time rewriting readmes than writing code.

Treat the readme like a journey/walkthrough of your product, follow an order, and keep it simple to understand.

I half agree.

I build apps with Claude Code, and I test them by having the AI click through the UI with Playwright. That's enough to check that things work as specified and nothing is broken.

But I think the purpose is different when an AI tries it and when a person tries it. To put it in extreme terms, AI is for UI and people are for UX. People find UI problems too, though: in my music player, songs got blocked from playing in Safari on a real iPad, and I only found it by using it myself. The things found in this article, like the jokes that didn't land or not knowing what the tool even does, are on the side only people can find.

(I wrote this in Japanese and used AI to translate it.)

Does the author aware the blog is unreadable on Firefox mobile? I might have something wrong on my phone too, but I don't have an issue with anything else.. https://imgur.com/a/ctriVnD

Yes. The amount of projects that don't just run is outstanding. Luckily docker container projects are inherently better at this is in terms of dependencies, but there are still often weird assumptions or medical incantations to get them during.

I've done this for internal dev tools! It's amazing how many assumptions you have about everything.

I've great success with friction logs: https://mikebifulco.com/posts/how-stripe-uses-friction-logs

If you are a platform team, going through this with your internal customers is both driving adoption and making your tools better. Highly recommended!

Not related to a README, but very much related to how programmers / creators speak (by which I mean type).

My way in to WordPress support back in 2004 was decoding answers to others from Photomatt and others.

A user would ask a question about WordPress and, for example, Photomatt would answer. His answer was always correct. Technically correct. But it didn't land for the question asker. They would reply with .. 'What?'

I would then replay with "What Matt has said is right, and this is what he means, this is the answer"

I gave them the information they needed in words they could understand.

It was not Matt's fault, it was not the user's fault.

It was translating in a way.

"They were the ones who caught the mistakes that no spell chequer could."

Nice, good article lol. I appreciate a joke or two in a readme but totally understand the annoyance, I think forgetting to actually say what the software does is super common as well though. Often trying to figure out if something found on github will actually solve a problem only to be met with a list of install commands.

Besides emojis, I find it too long. READMEs should be succinct and be like a switchboard to other docs (much like LLMS.txt tries to be for agents).

Also, it features an FAQ. FAQs are problematic (as in not often effective): https://passo.uno/what-the-faq/

Edit: Clarification

Same thing happened to me. The install command in my project's README was broken for one release. I didn't see it because it worked on my computer. I only found it when I tried on a new machine. Now we run that exact command automatically before every release.

This used to be standard onboarding practice everywhere I’ve worked.

Point new starter at the readme and get them to fix any issues (hopefully very few!).

What I love bout this is how closely it hews to the principles of design research. Same principles, applied deeper in the experience as LLMs make things more accessible than no code, or CMS before that.

All people creating, need to speak to other people. Loved reading this.

I'm so old that I remember when a software deliverable included documentation, and the product delivery was incomplete without documentation.

This is one of those things LLMs are really good at.

Create a new container or sandbox, copy in the git repo or point it at your staging docs, and see what happens.

Understandability depends on the audience.

E.g. as someone who doesn't "Fediverse", the intro section leaves me having no idea what an ActivityBot is or what an ActivityBot account is.

Also - formalize what can be. There may be e.g. opportunities to write scripts that can be tested and linted. I realize this isn't always possible, but I do think it should be ruled out rather than ignored.

Excellent article! Thank you for the reminder that I need to be spending more time with users… or hirelings :)

>My jokes aren't funny and are actively confusing.

You didn't have to murder me like that!

> I hadn't actually explained what the software would do.

This is my #1 annoyance when looking at a trending repo

> My jokes aren't funny and are actively confusing.

:’)

I think the problem is that this doesn't simulate for people who can't or won't read the manual

Coolest thing I've read in months.

Almost sounds like having a QA team is a good thing!

So usability testing?

Somewhat related question: what is it about READMEs that AI agents love to dump the most useless, hard to contextualise & comprehend, irrelevant rubbish into them that makes understanding a project and onboarding so hard?

It feels like like the AI agents can't help themselves sometimes, and the judgement exercised around what's included and omitted is baffling.

But maybe READMEs have always been this bad, and AI agents have raised the baseline?

Does anyone still write README files by hand now?

I hate READMEs with a gazillion emojis, too much noise.

And did it work?

"I took notes by hand (fuck feeding the machine)"

Closed. You are on a machine right now as am I, lets not pretend we don't like them for clout.

Given the agents.md I’m assuming the readme was just spit out by an LLM and the goal was to not read as LLM text. Problem is, it reads like you prompted it to be written in more simple language.

I just find it a bit misleading that you’re saying you want to talk to real people all while trying to clean up AI slop.

Now we have new ways to solve this problem: send Haiku or Luna to do task using computer use, but without access to code. If it can't complete it, or takes too long, docs are bad.

> My jokes aren't funny and are actively confusing.

Confession time.

I used to be prone to giving things slightly silly names, particularly unrecoverable structured exceptions. Examples include PancakeLandingException, ReallyBadException, CataclysmicException, ApocalypticDeathException, and the like.

And then years and years ago I used to work for a company called Redgate and I started a tradition of slightly silly messages when early access builds of our .NET products would expire, all based on Monty Python sketches and quotes. So, obviously, the dead parrot sketch featured in there.

So far, so harmless, but this did come to a head somewhat spectacularly and in a couple of different ways.

Firstly, in 2009 one of my colleagues used a modified quote from The Life of Brian as an expiry message on a build. Somebody who appeared to be some sort of religious zealot complained loudly to the company. We were both in LA at the time, with a couple of other colleagues, attending build 2009, so we woke up to a chain of something like 50 panicked emails in our inboxes with people expressing differing levels of outrage and/or amusement whilst discussing various grovelling apology options... until someone figured out that it was actually an elaborate troll that we'd swallowed hook, line, and sinker. I can't remember the name of the person who caught us out but, hats off, well played, sir, well played. It did unfortunately mean we became a bit more cautious and business-like with our early access build expiry messages.

Secondly, and this one needs a bit of context setting... I've always been a fan of descriptive and explicit error messages: there should be enough information in any error message that most of the time the user can figure out what's wrong and fix their own problem OR at least so that if they get in touch with support, then support can quickly figure out the problem and get back to them with a solution. I'm not a fan of unhelpful, information poor, obfuscatory, or cryptic error messages.

But when I wanted to cause an application to exit because there'd been an error related to tampering with our licensing code I played somewhat against type. I wanted error messages that would uniquely identify what had happened, making it easy for us to figure out, whilst giving the user no clue (because I wanted to make it very slightly harder for hackers/crackers - but let's be real: this would never have actually stopped anyone). So I used successive lines of dialogue from a scene in House where House is trying to guess who Wilson's girlfriend is. I have no clear recollection of why I chose this dialogue to reproduce, but... I did.

Anyway, this did lead to some slightly confused support requests coming in from users mostly trying to use the tools legitimately in slightly unusual scenarios, but nothing that was overly burdensome. That was until early 2011, when Greg Young - he of event sourcing fame - posted the following gist because he'd encountered an error that said, "Because I wanna ask you about your girlfriend. I must know who she is, or you would've told me her name.": https://gist.github.com/gregoryyoung/871736.

Not at all creepy, right? And, of course, it went viral on twitter. Cue another massive email thread although, this time round, people just thought it was funny. However, we did decide to make the error messages a bit more boring and, in the end, I just gave them numbers.

Mostly I'm just glad the error Greg got wasn't the final line of dialogue in the exchange between House and Wilson: "Yo mamma." That would have been bad.

In general, software is still Beta if a program requires a readme file to install and use.

It is under 5 minutes to write a shell/bat/make/cmake script for each platform to configure library requirements, import OS specific data, and enable GPU/NPU features. Then run through the application build, installation package with stripped performance build, and or a few regression tests.

Lets say you have 4k downloads a month on a small project, and it takes 1 hour for each admin to read/configure. You just saved about 5 years of your users lives reading your document. =3

>But it is really hard to ignore your own biases. Of course you know that certain commands require sudo and obviously when you wrote -foo you meant --foo and everyone knows that you have to reboot afterwards.

For God's sake, this is not "biases," wtf?? That's straight up just not reading/following the document you're supposed to be testing/reviewing. When I test my documents I actually follow them exactly, step by step, and I always catch these sorts of mistakes. Always. I always copy/paste commands because I know that is what the customer will do, so I have to make sure that works flawlessly.

Dude, if you actually follow your own document, you don't have to pay people to do it for you. Also, you can make sure the person you are paying doesn't ignore the document like you apparently do.

I stopped reading, I'm not interested in whatever else this dude has to say. I'm literally flabbergasted.

Maybe it's because my documents have always gone to real paying customers who have to get through this install, and not some hobby project I'm super proud of or whatever and I don't think I'm super clever? Idk.

Writing good documentation is difficult. From those who say "the source code explains everything", I think 80% are too lazy to write documentation in the first place.

Having said that, I found consistently that when a project has working examples, ideally documented a bit, aka explained, they tend to work much better than those projects that have no examples. Working examples often also help get into a project quickly and check out how it works. It helps to learn too.

READMEs are not useless, of course, but the quality varies a lot. I also know of folks who use AI slop spam to improve it, but while it may improve a little bit, it generates a lot of horribly to read text that makes no sense. I am noticing this with the ruby core dev team - they (almost) all suddenly have perfect language skills but it is more like an advanced babelfish translator. What they piece together here makes no sense. Claude in particular is now famous for this slop content. And I don't understand what it is used: real people read any of this AI slop? Because I just skip it or filter it away these days.

[flagged]

[flagged]

[flagged]

[flagged]

[flagged]

[flagged]

[flagged]

[flagged]

[dead]

[dead]

[flagged]

> I know someone is going to say "why not just ask an LLM to simulate a range of users?" The answer is very simple - I want to speak to real people. People are brilliant! They can make you laugh, you can see their cat when it wanders on to the call, they bring a unique perspective to the problem, and they're really happy when you give them a €25 voucher. Some will gladly do it for free and make you happy!

So what the author actually paid for was to interact with humans and the README checking was secondary - because, really, my own first thought was literally to ask an LLM check and try to follow the instructions in the README and pretty much any decent LLM (including several local ones) would be able to check if they're adequate and even suggest improvements (just don't let them write it for you :-P).

Nix.

I know, I know: It's complicated. But have you heard of AI agents?

But I just onboarded 4 interns on a project where all they had to do was

  1. Install the Nix package manager
  2. Install direnv, enter the project repo, and `direnv allow`
  3. Toolchain, git hooks, MCP servers, in-repo issue tracker, everything is available

Our project manager requested information that was available in the issue tracker. I told her, she could get all her answers by asking our agent, and it'd automatically reference the issue tracker. I figured I'd just need to show her how to install the Nix package manager. But no, she already had it because another project by another team depended on it.

Putting wrong information is README is so outdated when you have programmatic setup of your entire toolchain.