When I first started my professional dev career, I hated writing documentation. I didn’t think it was as fun as coding, and so, I never took the time to write it.
Over the years, as my job responsibilities progressed, I realized how valuable writing documentation is and that doing so ultimately helps me.
Before we go any further, let’s first clarify what documentation is.
Documentation is written “articles” or descriptions around a specific topic.
Documentation can be written for many things, like:
Explaining the description of classes, functions, and variables.
Explaining the “why” behind business logic.
Explaining how things in a system connect together (i.e., diagrams of database connections, APIs, servers, etc.)
Explaining how to get something set up (i.e., getting a developer machine set up to enable development work for a given repository).
Explaining guidelines (i.e., standard documentation around variable naming and patterns to be used).
Explaining troubleshooting steps for common problems.
Explaining the high-level logic flow of a specific feature (i.e., diagram flowchart).
As developers, we read documentation when:
When trying to install a “plugin” into our project, we read through its “get started” documentation.
When trying to troubleshoot a bug related to a “plugin,” We read through its “troubleshooting” documentation.
When we’re looking into contributing to an open source project, we read through its “Contributing.md” documentation.
When we’re setting up our machines to have a local working environment for an open source project, we read through its “Setup.md” documentation.
In this article, we’ll walk through the 5 ways that writing documentation helps you:
Improve your writing skills.
Help yourself in the future.
Help your teammates.
Free your time.
Help yourself stand out.
Writing skills are applicable to all aspects of your life as you need writing skills to be able to efficiently communicate the message you want to deliver. This applies to everything from your personal life to school to your career.
The more documentation you write, the more you hone and improve your writing skills.
That context of the code you write and how it all works together, as well as all the business logic around it and how everything is connected, will be gone in just a few weeks of not working on it.
When you have multiple codebases to touch or large codebases with multiple various complex functionalities, each piece will have pick-up time which will take a lot longer without documentation (pick-up time is the amount of time it takes to be able to understand a given task and start making progress to finish it).
I’ve personally found that writing the supporting documentation on what I’ve done helps me a couple of months in the future when I have to touch the project again.
If it’s code that you know you will not touch for a while, but will need to come back to, it may be worth the time investment to write the supporting documentation for it.
As we discussed above, code is complex and pick-up time takes a lot longer without written documentation.
If you work in a team environment where your code will be worked on by some other developer, then it will be even harder for them to pick up the context without written documentation.
By writing supporting documentation on what you’ve created, you’re enabling your teammates to be more productive.
Have you ever gotten a meeting invite asking how things work? 🙋♀️
Have you ever gotten emails asking how to do a particular task? 🙋♀️
Have you ever gotten emails asking why something works a particular way and it’s the same answer every time? 🙋♀️
Ever since I’ve started writing supporting documentation, I have had fewer meetings and emails around how things work/how to do things.
If I encounter a meeting invite around a topic that isn’t captured in the documentation, I create the documentation before the meeting (if I have time), send it to the meeting requestor, and ask them to meet with me if the documentation does not suffice. If I don’t have enough time before the meeting, I write the documentation afterward because I know that it will save me meeting time in the future.
I start an FAQ documentation on how to do specific tasks around questions that have the same answers. I then point people to these when answering emails. Now, they will know where to go to get their answers in the future. If they do forget, it does not take me much time to give them a link to the FAQ document.
If you help others to be more productive by writing documentation, you will set yourself apart and stand out.
I’ve worked with a lot of developers, and few take the time to write documentation. So, I am very appreciative when I encounter developers who enable me to be productive because they took the time to write up supporting documentation. Plus, it saves me a meeting request.
By writing supporting documentation, you set yourself apart and enable others to be more productive. In my experience, developers who help others be more productive are the ones who get promoted.
As with all things related to software development, documentation takes time and effort. Therefore, it requires some time management.
There are situations where there is be no time to write documentation due to critical project timelines.
We, therefore, need to be cognizant of when it’s appropriate to invest in writing documentation, and when it’s not.
Writing documentation helps you to enhance your writing skills while enabling yourself and your teammates to be more productive. It also saves you time from meetings and emails in the future. By enabling others and having good written communication skills, you will highly increase your chances of getting promoted.
But, we also need to realize that it takes effort and time. So, it is important that we are aware of when it makes sense to write documentation, and when it doesn’t.
View all Courses