Image Description
Software README template
Starting documentation from a completely empty file is surprisingly good at making you suddenly find seventeen other jobs that need doing.
So here's a starting point.
This is meant for an application or utility. Copy it, remove the sections you genuinely don't need and rewrite the rest for your project.
The template
# [PROJECT NAME] [One or two sentences explaining what the software actually does.] ## Features - [Main feature] - [Another useful feature] - [Another useful feature] ## Requirements - [Supported operating systems] - [Required runtime, if any] - [Anything else the user needs] ## Installation [Explain how to install or extract the software.] ## Getting started [Give the shortest useful instructions that take somebody from "I downloaded this" to "I've successfully used it".] ## Usage [Explain the main workflow, commands or controls.] ### Example [Give one small real example if that would help.] ## Accessibility [Describe keyboard support, screen-reader support and any relevant accessibility features or known limitations.] ## Configuration [Explain important settings or configuration files.] ## Troubleshooting ### [Common problem] [Explain what to check.] ## Reporting bugs [Where should bugs be reported? What information should somebody include?] ## Versioning [Explain the version scheme or link to release information.] ## Licence [State the licence and point to the licence file.] ## Credits [Credit contributors, libraries, assets and other work where appropriate.]
Don't use every heading just because it's here
If your software has no configuration, you don't need a Configuration section proudly announcing that fact.
A template is there to stop the blank page staring at you. It isn't paperwork.
The first paragraph matters
Write it for somebody who has never heard of your project.
"This is the new version of my old program" tells an existing user something. It tells a new visitor almost nothing.
Say what the thing actually does.
Getting started should actually get me started
If I need to read six other pages before I can make the program do one useful thing, the README has probably missed its chance.
Give me the shortest successful path, then link to the detailed documentation.
Accessibility
I think this deserves a place in more software documentation.
If you've tested with NVDA, say so. If everything can be used from the keyboard, mention it. If there is a known accessibility problem, say what it is rather than hiding it.
Further reading and external resources
Back to Writing a useful README | Next: Game README template