Consider to add best practices for writing a good README file
After watching the FOSDEM 2025 lightning talk "How to Write a Killer README", I think this is something that should be shared with our community and incorporated either directly in the Eclipse Handbook or by referencing an external guide.
The Handbook references a few things that should be mentioned in a README, but it's spread out over different sections:
- "All members of the various communities that grow around your project expect to find a README file in the repository root with information about the project." (https://www.eclipse.org/projects/handbook/#incubation-development)
- "If a repository belonging to a project is unmaintained or deprecated and will not receive any further updates, it is good practice to clearly indicate that in the corresponding README.md and SECURITY.md files of the repository with a migration path if applicable." (https://www.eclipse.org/projects/handbook/#resources-archiving-repositories)
- "Organisations who are investing in an open source project may want to provide links on the project website (or in other content related to a project: a README file, for example) to related professional services that they offer." (https://www.eclipse.org/projects/handbook/#resources-website-services)
- tl;dr: Should include links to the official website, terms of use, privacy policy, code of conduct and communication channel guidelines (https://www.eclipse.org/projects/handbook/#resources-external-legal)
- "contribution guidelines are typically found a CONTRIBUTING or README file in the root of every source code repository" (https://www.eclipse.org/projects/handbook/#contributing-contributors)
- "Specification project teams should make the nature of the project clear in the README files in their repositories" (https://www.eclipse.org/projects/handbook/#specifications-faq)
-
As described below, legal and other metadata files must be included in the root of every source code repository.
../project.git ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE.md ├── NOTICE.md ├── README.md └── ...
A specific section about a good README could contain the following best-practices:
- Explain what the purpose of a good README is, in general
- What it should contain, e.g.
- What does the project do? What does it NOT do?
- How is the project different from other similar projects
- Describe ideal use cases
- How do people use the project (social proof) / examples
- How to get started (easily)
- Link to supporting organizations / companies
- Link to contributing guide
- Link to security related topics (how to report a vulnerability, etc)
- Link to communication channels
- Legal links
- Must-haves vs. nice-to-haves
- Eclipse-specific standards (e.g. legal documents)
- Links to projects that already have good README files