The importance of a README
Yesterday, I wrote about how comments on your code are really important when you have ADHD.
Today, I wanted to talk about the second component of good documentation: the README.
A good README file adds a ton of value for anyone else working with a project (now or in the future). But because ADHD working memory is kind of shit, it’s also really important for you and your own code.
Things I like to see documented…
- A Quick Start guide on how to run the site or app and see it working in a browser.
- The architectural philosophy behind it. How is it built? What are the main tools powering it? Why were those choices made?
- The project structure. How are the files organized and arranged. Sure, I can (usually) figure that out by digging through the code, but it’d be nice if I didn’t have to.
- The tools and libraries that are used. If there are third-party libraries, link to the docs. If there are internal tools, include details on how they work.
- How to run a build. What commands I need to run to turn source code into working code, run tests, and so on.
Can you reverse engineer this stuff by looking at the package.json file, reading the source code, and so on?
Sure! Maybe. Probably? (Depends on the day, right?)
But a little time spent writing a README up-front can save you (and other developers) hours of headaches later.