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.

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.

> 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".

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.)