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 them.
Over the years, as my job responsibilities progressed, I realized how valuable writing documentation is and that, ultimately, doing so helps me.
What is Documentation?
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 and APIs and servers, etc)
Explaining how to get something set up. (i.e. getting a developer machine setup to enable development work for a given repository)
Explaining guidelines. (i.e. a standards 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)
And more.
As developers, we read documentation when:
Trying to install a "plugin" into our project. We then read through their "get started" documentation.
Trying to troubleshoot a bug, and we find our way into a "plugin". We then read through their "troubleshooting" documentation.
When we're looking into contributing to an open source project, we read through their "Contributing.md" documentation.
When we're setting up our machines to have a local working environment for an open source project, we read through their "Setup.md" documentation.
And more.
How Documentation Helps YOU
In this article, we'll walk through 5 ways writing documentation helps you :
Improve your writing skills.
Help yourself in the future.
Help your teammates.
Free your time.
Help yourself stand out.
1. Improve Your Writing Skills
Writing skills are applicable to all aspects of your life. You need writing skills to be able to efficiently communicate the message you want to deliver. This applies in everything -- from your personal life to school to your career, any career.
The more documentation you write, the more you hone and improve your writing skills.
2. Help Yourself in the future
That code you write and how it all works together, as well as all the business logic around it and how everything is connected -- that context 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 finishing it.)
I've personally found that writing the supporting documentation on what I've done helps me a couple months in the future when I have to touch the project again.
If it's code 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.
3. Help Your Teammates
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 would be even harder for them to pick up the context without written documentation.
By writing supporting documentation on the what you've written, you're enabling your teammates to be more productive.
4. Free Your time
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 less 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 is not suffice. If I don't have enough time before the meeting, I write the documentation afterwards because I know it will save me meeting time in the future.
I start a FAQ documentation on how to do specific tasks and around questions that have the same answers. I then point people to these when answering emails. Now they know in the future where to go to get their answers. If they do forget, it takes me much less time to give them a link to the FAQ documentation.
5. Help Yourself Stand Out
If you help others be 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 the ones that enable me to be productive because they took the time to write up supporting documentation, and it also 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.
Documentation Caveat
As with all things related to software development, documentation takes time and effort. Therefore, it requires some time management.
There would be situations where there would 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.
Wrap Up
Writing documentation helps you 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 highly increase your chances of getting promoted.
But we also need to realize that it takes effort and time, and we just have to also be aware when it makes sense to write it, and when it doesn't.
Top comments (6)
i am presently doing this for my company and i must say it is worth every time spent in writing it. Now my teammates do not have to be stressing on how this or that works or who wrote a code last, they just read up the documentation and get to work.
truthfully it is time consuming but then it deepens your knowledge on the functionality of your code.
Yes, it definitely takes time and it's an investment! It helps share knowledge amongst team members easily without additional meeting times. 🙂
I think investing time in writing documentation is one of the best way to understand something DEEPLY (very similar experience to learning something to teach it)
If you build a product that targets developers, it might be the best way to spend time, because it will most definietly improve UX, cut support cost and just straight up allow more people to use it.
This is helpful. Thanks!
I saw "writing documentation", I hearted. I'm weak like that ;)
I agree. In the end we develop code so that others could understand it.
Great post !!