There is a profound need for a proper README file in every project one works on. It's where very basic but key information regarding the projects should be contained, but not only that. A good README is made by having a bit more than basic project information. What exactly? We will go into that in this document.
This post's target audience are beginners who have yet to believe in the power of documentation. Also my experiences here are mostly relevant to my work - so web based apps, depending on the app this will vary, however I think the advice below is a good start.
Technology
Usually the README we work with have .md extrension, the marking of a Markdown file. Markdown is something that let's us format text in a certain way. We will stick with that and assume Markdown is used in the README file for convenience's sake. Make note though, it does not have to be the case.
Sections
Title
Start your README with a line of a project name, like this: # Example Project. It's obvious but needed. # marks a given line as a header in Markdown.
Summary
Here you must put basic information about the project.
What system component it is? For example - API, Worker, frontend, library.
What functionalities it includes? For example - This is invoicing API for foobar system.
Some additional context - Who the stakeholders are (for who is the project intended), what the business need/idea is behind this application, who are the actors, end users, few words about project from business perspective.
The summary should also contain and use wording that is closely tied to the Domain of the problem/need that the project is solving.
Tech stack
This section should contain the most important packages used to build the application, 3rd party dependencies, services etc.
This will enable the reader to gain a quick understanding of application dependencies and the technology used, problems solved.
One should not forget to link the used technologies to proper websites, resources to ensure no ambiguity.
Local development setup
Write down a list of steps needed to bring the project up for development locally, on the developer's machine. Other than that you should also add a list of commonly executed operations like cleaning the databse; (re-)setup the project from scratch; migrate the database. Same with project-specific knowledge - this section is a good place for such things. For example - handling l10n, i18n with a 3rd party service like PhraseApp or OneSky.
Local development setup section should be prepared while having less technical people in mind, as stakeholders which not always are tech-savvy, might be using it. Additionally Local Development setup should be as automated as possible.
Deployment
Briefly describe how the application is deployed, where to look for more detailed explanation if needed, what is the deploy setup or a few words about CI/CD.
Contributors
Leave some kind of list of people who contributed to the project or are key people in the context of this project. This can be useful when jumping from one project to another after some time, as it allows one to identify the context holders very quickly.
Aaand that's it.
Check out my other articles:
Three types of managers - which one are you?
Tenancy pattern in a SaaS product
How I created my own blogging system in less than 100 lines of code
Pyenv, poetry and other rascals - modern python dependency and version management
Top comments (6)
I do appreciate and like your post. I must say, however, that it is just not possible to generalize the contents of a
Readmefile without taking into account the purpose of the object of the documentation, plus the purpose of the act of documenting.For example, very different
Readmefiles are needed when documenting a Nuget or NPM package than what you would need when documenting a folder with deployment YAML or Docker files. So I'd take this post with a grain of salt as they say, and make sure to always think about the purpose of the action and the object of the action.I think your comment aligns with @gbhorwood , I'll add the target audience at the top
Usually, some poeple write development instructions and other things in CONTRIBUTING.md or DEVELOPMENT.md.
So if you are making a library, you can maybe use that file instead!!! ^^
i always like to add an "intended audience" section right near the top. something like "this document is intended for systems administrators who are running high traffic uucp servers" or something. it's always good, i think, to help people figure out quickly if this is the document/package that meets their needs.
Good advice, thank you! Added.
Simple words and good explanation
Thank you