Developers become developers because they like to code. Many have taken up coding as teens after school, or during after-hours after their cubicle job. They realize how much power they can get from their IDE and their command line, and they get addicted to it.
Even when developers land that dream job where they can code all day, many keep their side projects going in the evenings and during after-hours. I personally know developers who keep coding on the train after they leave their office — because what else is one going to do on a train?
Coding is a way of life. It’s as simple as that.
There’s just one little problem: Coding is not the only part of software development.
You’ll also have to work with a team, sit in meetings, write emails, and write documentation for your code.
And in the long run, what will make or break your career won’t be the emails you wrote or the meetings or the contributions you made during meetings. It won’t even be the code you wrote, believe it or not.
The deciding factor between a career that has a lasting impact on your company and one that doesn’t is just one thing: your documentation.
In two years, nobody will understand your source code
Languages and frameworks come and go.
Just a few years ago, Python2 was the status quo of back-end programming and data science. Then Python3 came, and everything that was in Python2 was out of date and didn’t work with any new code.
There always will be some language, some framework, some technology that will do the task at hand better and faster.
Or maybe it’s just trendier.
Either way, many junior developers — and those tend to be the majority of new hires — won’t bother with the old languages any more.
They’ll rewrite your code.
Or forget about it completely.
Your code doesn’t exist in a vacuum
Even if your code is in a fairly popular language, nobody will understand it by reading just that code.
Maybe you’re writing part of the front-end of an application. But without at least some knowledge about what the backend does, nobody will understand the code in-depth.
And, as many devs can testify, in-depth understanding is crucial for maintaining code.
You can’t just add a front-end feature without thinking about back-end support for it. Or add a feature that looks nice in your app but which, at its core, nobody cares about.
Team members come and go — even you
Documentation is the best friend of on-boarding.
Think about it: How many new hires has your team had in the past couple of years?
And how many existing team members have had the time and patience to explain every piece of code to these new hires?
Developers need to ship. Most devs just don’t have the time to invest a couple of months to get a new team member up to speed. Your manager doesn’t care about your mentoring abilities. They want to see results in the form of code.
Documentation is the solution. All that you can explain you can also write down. Once written, it can help one new hire. Or two. Or a hundred.
Documentation scales. And saves time.
Besides, one day you won’t be around to mentor new hires. Maybe you’ll move on to a higher position. Or you’ll change companies. Or you’ll be on sick leave when something happens.
Either way, when you’re not there anymore, your documentation will work for you.
Your documentation is your legacy.
Managers won’t look at your source code anyway
Developers who code for a living won’t understand your code in-depth from reading it. Your manager won’t understand anything at all.
Most managers know this. That’s why they don’t read source code.
It’s not laziness. It’s effectiveness.
Managers need to decide which resources to use on which project, which team member to shift where, and so on. Business decisions.
At the core of it, though, they’re managing the people that make code. They’re managing code at a very high level.
You can’t manage code if you don’t understand anything at all. So managers read the code documentation.
Besides, if you consistently produce great documentation for your code, your manager might notice.
And give you a promotion.
How to make documenting enjoyable
Yeah, all the above reasons are good reasons to write better documentation. But developers don’t want to write like they’re Stephen King. They want to code like they’re Bill Gates.
Documentation is that pain in the rear end that comes when you should feel satisfied because you’ve just written amazing code.
You can make it less painful, though.
Use Continuous Documentation and write up your docs while you’re coding. Use smart tools to write and maintain your documentation.
Only a small proportion of devs are doing this. But that proportion is getting bigger fast.
More and more devs are realizing that they need to upgrade their documentation. It’s a necessary evil.
Continuous Documentation, or the habit of contributing to your documentation whenever you make a change — however small — makes the pill easier to swallow.
Famous last words
The route to making a lasting impact in the world of software is curvy and bent, and you’ll need a share of luck as well.
If it were just about writing amazing code, it would be a straight road.
Documentation makes the road to achieving success harder because it’s a task that many devs don’t enjoy.
Cut it into little pieces, and document every change as soon as you make it.
Your career will thank you.
Read More
Ari Joury