Skip to content

Latest commit

 

History

History
47 lines (25 loc) · 2.32 KB

Readme - Example.md

File metadata and controls

47 lines (25 loc) · 2.32 KB
Raw

'What makes a good Readme'

The What. The readme should be and is probably the first place anyone interested in your solution will start. It is the window into how awesome the project and the team working on it is!

Screenshots

Including screenshots is a great way to visualise your project and show off what the team has done.

The Why. So what's the motivation behind doing this? What problem is this fixing and the expected benefits? This is you "one line" sales pitch to get contributors & new team members excited about working on something great.

I'm Sold - tell me how

This section should allow anyone to be able to pull the repository and go from "zero to hero" in the smallest possible time.

Build / Installation

Provide all the relevant information required for the reader to be able to build the solution. This should match the same scripts/methodology that are used in the CI.

In most cases there are multiple methods that could be use to build / test / run the project. Providing the most common methods to achieve this will give the least resistance or issues to get the project running. Where applicable examples and explanations should be provided.

Test

What tech/frameworks are used to ensure confidence that the solution meets the expectations. Provide code examples and/or screenshots where applicable.

Running or using the solution

Provide a step-by-step guide to running and/or consuming your solution.

Known issues and compatibility

Be honest and upfront about what compromises have been made. They will be found out regardless so be transparent

  • Does this have any known issues that will affect the build? Link to issues tracker
  • Does this use any legacy technology and why?
  • Does it rely on certain environments? e.g. Can this target any O/S? Can it run in the cloud? etc

Build status

Linking into the current CI status is a great way to feedback to the user what to expect

Where next ?

Providing signposting will allow the reader to quickly delve deeper. API documentation and ADR's are the next logical steps to understanding the DNA of your solution.

Contribution & Code of Conduct

Let people know any coding styles that are employed, is there a git strategy and project structure this solution follows. What is the code of conduct for working with the team.