README file(s) is a ubiquitous document/artifact in any typical software development source code repository. Their role is invaluable especially during accelerating new team members’ on-boarding into an existing project.
My main objective in writing this post is, describe typical characteristics of README file readers and provide recommendations to my contemporary README author(s) in improving their README content.
My Approach To README files authoring – Empathy
I have authored README file(s) multiple times and my approach generally is embracing Empathy while authoring such file(s).
Empathy meaning - the ability to understand and share the feelings of another
Basically what I mean is, while writing README files, I feel empathetic-ally about personas of my README file readers i.e. readme file readers characters and also consider different extremes of each point discussed in the README file.
Personas means - the ideal target readers we are aiming to
communicate with and design for the whole README content.
Empathy 3 Types
Before we dwell more into personas, let us touch briefly on “Empathy” relevant to authoring a README file.
Empathy 3 types are – Cognitive, Emotional and Compassionate.
- Cognitive – mental processes involved in gaining knowledge
- Compassionate – thoughtful (an apt synonym for Compassionate word)
- Emotional – demonstrative (an apt synonym for Emotional word)
Personas Types
I have observed generally README file(s) readers have below personas:
- Impatient ( to read the full README file content)
- Ignorant ( on some or all topics discussed in the file)
- Highly Knowledgeable ( about the topic discussed in the file)
- Confused ( uncertain whether he/she reading right README file)
- Spoon-feeding ( expects every step to be accurate, detailed with next best actions described)
- Smart (knowing where and what to look for in the file through searching of file)
My Recommendations to Authoring README files
Considering the above mentioned factors (Empathy types, Persona Types), below are some of the recommendations while authoring a README file:
| S. No | README file authoring Recommendation | Applicable To Whom or Factors |
| 1. |
File introduction with Objective sentence or paragraph – (a) highlight preconditions; (b) mention keywords related to the subject discussed in the file (c) ensure in the introduction you crisply mention start state to finish state i.e. what a reader does from the start steps in the file and achieves after the last steps in the file. |
Personas: Confused – with preconditions decides relevancy of his/her need; Smart – with keywords navigates through the file from the start to the end; Spoon-feeding – not much useful but can become confused in the early stage of file reading because not much steps to perform, assuming will hold on their patience and read further down might help them satisfied with the file content Empathy Types: Cognitive with this kind of introduction section |
| 2. | Use of syntax shell commands – this helps copy paste the commands and execute them directly in Linux command line |
Personas: Spoon-feeding – they find this syntaxed commands copy and paste very useful Empathy Types: Compassionate – increasing the thoughtfulness of your file reader through syntax highlighted background color of such commands |
| 3. | Mentioning Extreme Conditions – it is very important to mention happy paths and exceptional scenarios like what to do if an exception occurs. |
This is help full for all personas and empathy types |
Conclusion:
I will try to keep updating above recommendations and I hope you as a README file author, above personas and empathy types might help you in authoring in an effective and efficient way.