For most developers, the Readme file is the first resource they are accessing. It contains information on how to set up the project, instructions and a lot more information. E.g. if the version of the software is beta or stable, which git workflow the project team uses, under which license it's running and so on.
But besides all the technology things you should consider putting in some more information.
How To Start Your Readme
Start with something positive, with something like a project-, company- or team- claim. Something that shows the team that you are one team and that you are working together.
We are one team - with no alpha leaders and no beta teams
Contact List
It's important to know who is the contact person or responsible for which topic. Who is the Project Lead? Do you have a Lead Developer? Do you need contact with other teams, 3rd parties, other disciplines, ...? Put them into the Readme or at least link to the platform where they are documented.
## Team - Contact Persons
You can find a full list of the team at
[confluence](https://linktoteamcontactpage)
Be Human - Always
How do you want to work as a team? What is important for you? At my recent project I set up a readme file and it was important for me to give a clear picture of what we should focus on as a team. We didn't have a lot of time for the applications we needed to build. In an ideal world, I would define those together with the team.
## Be Human - User. First. Always.
* We work for the best overall result and
act in the interests of the whole.
* We trust each other and are open
to new input / opportunities.
* We treat each other with respect,
empathy and believe that everyone is acting as their best.
* We make each other successful and give a hand if needed.
* We keep it simple.
Put your "how do we want to work" statement not at the end of the document. It's important and should be in the upper part.
How To End The Readme
Close the readme with a something claim / message. I chose to use something from the beginning in another term.
> Together we can make a change. Together we can do it.
As one team with no alpha leaders - no beta teams 💖 🤓 ❤️ 💻
We have built applications that help to fight COVID19. It was very clear that we need to do a lot of over-hours to make it in time and to react to the ongoing pandemic. So, the following part of the Readme was the most important one for me. I wanted to make very clear that NO project is more important than the health or (the family) of every team member. What made me happy was, that the team often quotes that part of the Readme and looked after each other. It helps that it was clear, 'your tech lead put this into place at the beginning, don't be afraid of calling in sick or taking a break'. And it worked, I'm very glad of that fact and proud of the team.
## !important 🚨
Please remember that your (mental) health
(and of your family) comes first.
If you are facing a health problem,
no matter at which point of the project,
please inform at least one person
of the team and take a break!
That's why I recommend putting some personality into Readme files, especially if you are the tech lead/ lead developer. Lead by Example.
What are you putting into your project Readme file on the root level?
Top comments (4)
Being honest I've never thought about ReadMe in this context. Thinking about it right now, this Readme with soul, may make someone's day, and propably remind him of important things like family.
Very good article. I really enjoyed this one!
Thanks a bunch :)
A small hint regarding inclusive language. You used "him" in your answer and I'm pretty sure you didn't want to exclude other genders. Use "them" instead of "him" - that includes everyone.
Happy Thursday
Thanks for protip. english is not my primary language, so when i was writing this comment I didn't see that as something that can exclude other genders.
Happy Thursday
This said "Be Human"
But that felt massively robotic to me