Different people have different views about what constitutes a good README document for a software project. I think it should be vehicle for delivery of the bare minimum knowledge necessary to convey why someone might want to use it and how.
Imagine you're a trainee who was given a URL to the GitHub page on your first day. You have only the bare resources needed to run the program, but none of the knowledge about it.
What information would you need? Make certain to add that information:
- Brief description of project aimed at somebody who might need it, but hasn't necessarily ever heard of it.
- Link to the projects's home. This might be a github.io site, a Confluence page or a wiki.
- Minimum requirements to use the software. What OS, toolchain, developer tools and pre-installed libraries are vital in addition to the project itself?
- Exhaustive, foolproof, concise instructions on how to use the software. Given a local copy of the project, you must be able to type out these instructions, ideally with your eyes shut, and when you open them, the program (and its dependencies) is configured, built, tested to a basic level and installed on the system (privileges permitting).
- Follow-up information such as: troubleshooting, support forums, bug tracker, developer documentation and ways to contribute.
What information wouldn't you need? Make certain to omit that information. The main reason to omit things are because they are only useful to developers, not users, e.g.:
- Code documentation belongs to document generation tools like Sphinx and in the source code itself.
- Project development details are a matter for project management tools like Bugzilla or GitLab issues tracker;
- Team organisation and intercommunication is a matter for the wiki or developer forums.
Keep the formatting simple and clean.