This article explores what makes a great project README, how Appsmith made ours as accessible as possible and provides examples of other effective READMEs.
Two universal facts about user documentation:
Documentation is really important. We are really bad at writing it. We don’t have good theories on what makes for useful documentation. That is except for the four document model, or Diátaxis.1 I’m glad that people use it. I’m also a little frustrated that people use it even when its inappropriate. My problem is that it’s not a universal or comprehensive model: there’s a lot of documentation people need to write that doesn’t neatly fit the model.
For years, my self-education was stupid and wasteful. I learned by consuming blog posts, Wikipedia articles, classic texts, podcast episodes, popular books, video lectures, peer-reviewed papers, Teac…
Boustrophedon is a style of writing in which alternate lines of writing are reversed, with letters also written in reverse, mirror-style. This is in contrast to modern European languages, where lines always begin on the same side, usually the left.
Free and liberated ebooks, carefully produced for the true book lover. Download free ebooks with professional-quality formatting and typography, in formats compatible with your ereader.
The following first appeared in Lit Hub’s The Craft of Writing newsletter—sign up here. Here, in short, is what I want to tell you. Know what each sentence says, What it doesn’t say, And what…