Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

First you should decide who the intended audience of your documentation is. Who are you trying to help, and what are you trying to help them do?

Then, partition your mind into two halves. The first half contains everything you know about the project, and the second half contains everything your imaginary new reader knows, which may be nothing.

Identify each difference between these two bodies of knowledge and, starting with the largest and simplest, write down what the reader needs to know in order to transition from one state of mind to the other, in as succinctly a way as possible.

If you start rambling, go back and edit.

I find this works for explaining many things, not just software projects.



Consider applying for YC's Fall 2026 batch! Applications are open till July 27.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: