You wrote a small command line tool to seed test data, mostly for yourself. Then a colleague in another team saw it in a demo, and now three teams are trying to use it. Every morning there is a new message. How do I install it? Which config file does it read? Why does it fail on my machine? You answer each one kindly, in a private chat, and by Thursday you have explained the same setup steps six times.
Every one of those messages is a page of documentation that only one person can read. The answer exists, but it is scattered across private conversations, and the next person will ask again. It is time to write it down once, in the place people will look first.
Start with the first five minutes, not the whole tool. A newcomer wants to know three things. What does this do, in one sentence? How do I get it running? What does it look like when it works? Put those at the top, in that order, with a command they can copy and the output they should expect to see. Most people never read further, and they should not need to.
Write for someone who knows nothing about your setup. You stopped noticing that the tool needs a particular version of the database, or an environment variable you set two years ago. They will not know. Every assumption you have forgotten is a question waiting to arrive in your messages.
Use the questions you have already been asked. They are the most honest outline you will ever get. If two people hit the same error, that error and its fix belong in the document, word for word, so it turns up when someone searches for it.
Then test it properly. Ask someone who has never used the tool to follow the README while you watch, without helping. Stay quiet even when it hurts. Wherever they pause, frown or open a chat window, the document has a gap. Fix it, and ask the next person.
From now on, answer new questions with a link and a short sentence. Good question, I have added it here. People learn quickly where the answers live.
You will spend an hour writing it. You will get back that hour within a week, and so will everyone who uses the tool after you.
– Asael Shinder
Top comments (0)