Readme's - more than only tech instructions
Tags: documentation, git, leadership, productivity
Published: 2021-04-06 11:09:54

---
title: Readme's - more than only tech instructions
published: true
description: Why I recommend and how to put in some personality into readme files.
tags: #documentation #git #leadership #productivity
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yvp9o7fe350y4o6e1kuy.png
---

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.
```markdown
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.
```markdown
## 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.
```markdown
## 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. 
```markdown
> 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.
 
```markdown
## !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](https://dev.to/s2engineers/lead-by-example-5cm3). 


What are you putting into your project **Readme** file on the root level?