DEV Community

Cover image for Readme's - more than only tech instructions
Feli (she/her) for Studio M - Song

Posted on • Updated on

Readme's - more than only tech instructions

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
Enter fullscreen mode Exit fullscreen mode

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 
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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 💖 🤓 ❤️ 💻
Enter fullscreen mode Exit fullscreen mode

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!
Enter fullscreen mode Exit fullscreen mode

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 (3)

foxnacity profile image
Damian Nowak

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!

kotzendekrabbe profile image
Feli (she/her)

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

foxnacity profile image
Damian Nowak

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