Readme files are often overlooked by teams.
The readme files for Git repositories are essential. I was almost always disappointed by the ones student teams submitted. They were usually too vague and left out crucial details. This was even true when I provided template repo with a structured readme file for them to use in submissions.
The one submitted were usually the same as the template, apart from team member names, or had general details. Some, were happily better, and did what was needed.
Readme should cover the basics you need to know
I always want to know the same things in a readme file for a repository. What it does, how to build, run, and test it. I also might want to know what’s required to develop the app further, and how to deploy it too.
I’ve found that my readme file has evolved over the last year as this project developed. I started with everything in one file, and clear sections covering what it does, requirements, how to build the app, how to run it, and how to test it. I also had notes scattered about for each section too, which I figured would be useful for whoever gets added to the team later. This included links to relevant web pages on the libraries, useful examples, plus error messages that might turn up, and how to resolve them.
I also keep a section on ‘issues’ which are things that need to be monitored and eventually resolved. This is a sort of an unprioritised ‘to do’ list of tasks, and memos to myself. I keep it here so that it’s never lost, and can also be dug out of a previous commit if required. Yes, they could be done as ‘issues’ in the project, but that is too formal for my purposes. Given there is mostly only me, this works fine. I can review it, and attend to as required, and then remove items as they are resolved.
Readme can be more than one file
Some time ago I realised the one file was too big. I added more files: requirements, development, running, testing, production, and issues. Each is linked to the more basic readme.md file. Splitting the original into more specific files makes managing the information easier, and clearer to readers too.
Now the readme file covers the general purpose of the app. It covers bigger issues clarifying the folders, and some external libraries that are used. This keeps everything more manageable.
Some details should never go into a repository. Some of the files mention where external information is kept, and how it is integrated. This keeps all details confidential, and reminds you, and others where things are held.
Agree readme purpose and role in the team
As there is mostly just me working on this, I can do it my way. There is no discussion about how or why I’m doing things as I am. I can make the changes, and add relevant comments in the right file. Now I can remember why I made some decisions, such as when I changed the testing tools. If I worry that I might want to find something I cut from the readme, then I add a date. This to makes it easier to dig out the details from the relevant commit if required later.
Talk to each other about the readme file
When collaborating in work you need to be clear how and when things should go into the readme files. I noticed that when I was able to collaborate with another person, that I had to suggest when we add a note about something. I would explain why it should go into a file, and then we’d do that. These were often little things about the right order, and commands for different steps in development, or running the app from a device as we learned how to do that. Anything that saves time for next time, or creates a checklist of sorts, should be added.
This worked fine as we were mostly working side by side. If we were working separately, then we’d need to agree a policy about the types of things to add, and when. Alternatively, we could agree to add odds and ends that ‘might’ go into the files to the issues.md file, and discuss them later when we were together again.
This reminds me: we should discuss a team agreement at some point. That way we both know how we want to work together.
This post is part of a project pulling together my materials and ideas about Teaching Team Collaboration: the Human-Side of Software Development for software development to students.
If you’d like to be notified of future posts, then please sign up for more using the adjacent form. When you sign up, then I’ll send you a free copy of the collaboration rules as a PDF from the book. You can also follow me on LinkedIn
The ideas above are from my book 101+ Ideas to Improve Team Collaboration, which covers all of these little things that students can do to improve their collaboration. Also available via Kindle.