The README
Create a top-level README and make it the entry point for developers, so they can quickly get the system up and running.
Ask new starters to begin with reading this README, and in turn, it should provide enough information to get started.
Write as little as possible. People don't read, they scan, and very few are interested in reading a README. Developers will look for keywords and code blocks to copy. Don't let important information get lost in the sea of words. Don't waste attention.
Few things scream neglect as an outdated README. The less you write, the less will become obsolete tomorrow.
When you need to write a lot of instructions, consider automating the complicated steps. Solve the problem once instead of letting everyone after you struggle with it.
What to include in a README?
- Instructions to get the project working in a dev environment so people can start being productive fast
- Brief notes on quirks, known issues, peculiar things in the project that would surprise others.
What to leave out?
- List of technologies in use, they should be evident from the codebase or
package.json. - Do not copy or link to 3rd party documentation that is a Google search away.
- In general, omit everything that is obvious or can easily be found out from the codebase, or is not relevant to writing software.
Making others read one README is an achievement in itself. By default, I'd avoid adding separate READMEs to the individual workspace modules.
Last modified 3yr ago