🏁
Best Practices
  • Introduction
  • The Big Picture
    • Principles
      • Software engineers solve business problems
      • Programming is a social activity
      • Attention is the most precious resource in a project
      • Simplicity is the best ally in the long run
      • The only problem to solve is the one we have today
    • Architecture
      • Domain
      • Services
      • Persistence
      • HTTP
      • UI
    • Naming
  • Constraints
    • TypeScript
    • Monorepo
    • Monolith
    • Versioning
  • Source code
    • Declarative programming
    • The README
    • Modules
    • Folder structure
    • Code formatting
    • Code comments
  • The Outside World
    • Runtime configuration
    • Logging
  • Testing
    • The purpose of testing
      • End-to-end tests
      • Integration tests
      • Unit tests
  • Tools
    • Git
  • Resources
    • Resources
Powered by GitBook
On this page

Was this helpful?

  1. Source code

The README

PreviousDeclarative programmingNextModules

Last updated 5 years ago

Was this helpful?

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. .

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.

Don't waste attention