As Github repositories and accounts become more like resumes, the README for our software projects are become more important as the first impressions to prospective users and/or future employers.
That said, it is important to invest the small amount of time to make a lasting impression. The README can serve as an after-thought when we are engrossed in our code; however, it is the first thing that prospective users sees and open-source software projects are often graded on their documentation.
I would suggest approaching the README as a living document to be updated throughout the life of a project. As new features and requirements come about, then update the document periodically. Treat it as a periodic task to be completed, and it will be less of a chore.
If starting a new README, I would suggest the following:
- Know Your Audience – Write for your intended audience in an approachable manner without too much technical jargon. Write with detail for the technical users but also broad enough for prospective employers and/or management who may not understand the lingo of your domain, language and/or framework.
- Keep It Simple – I personally love lists (such as this one) so bulleted lists go a long way to illustrate your points and all they required are an asterisk before each one in markdown syntax. Shorter sentences and paragraphs make the points easier to grasp.
- Stay Organized – Use headings liberally in your document to organize your thoughts and convince your reader. After all, we all wish to make a point so that our read is sold on our product, i.e. our project and/or work.
Writing style is a deep and broad topic but in general, write in a voice that is comfortable to you, professional and cuts to the point. Respecting the audience by communicating effectively and efficiently goes a long way.
Some other points for writing style that I find useful are as follows:
- Write in Your Voice – Assume that the README is completely public since it is posted online (or may be circulated), so keep things professional but also in your own voice. Avoid slang which seems unprofessional and/or lingo/jaron which may throw off your audience.
- Retain Your Audience – Stay organized, hit the key points then move on. Treat the README as an email being directed to a future employer or supervisor – write professionally and to the point without belaboring the point.
- Have Fun – Make your points but add that hint of personality when writing in your own voice. Avoid slang but write in a tone that is informative, instructive and not too stiff.
In conclusion, the README is a public document that sets the first impression and tone for your audience and drafting/updating it is a small investment of time that can go a long way so please be sure to invest in it.