Image of Austin Gatlin's face
June 26, 2022


The point of documentation is to be understood. Good documentation is reader-oriented. Reader orientation means that the reader's needs are met by visiting the documentation. Readers consult documentation for multiple reasons, and so ideally each of these reasons are addressed appropriately in the documentation. Also, tedium is a universal deterrent, and so being able to quickly get where you want is important. (It is not tedious to read a long tutorial if that's what the reader wants. It would be tedious to read through a long tutorial just to remember where some reference information was hidden within it.)

According to the divio documentation system there are four types of documentation: tutorials, how-to guides, explanation, and reference. I am interested in the idea of explicitly creating top-level sections in a README for each of these.

Documentation as Ideation

PRFAQ is a strategy popularized by Amazon as a way to discuss product ideas before they exist (see ideation). I am inspired by this fake PRFAQ idea, and wonder if you can treat a README in a similar vein as a PRFAQ. That is, write the complete README before you write anything else. Write the explanation, reference, and how-to guide in the least. If you still like it by the end of it. Build it.