You might feel like you don't really have a problem, but statistically speaking, you probably do. And even if you do have documentation, there are ways of making a better habit out of writing it.
We'll go over a few of the go-to excuses(not to be confused with "excuses for using goto") and discuss approaches to fixing this.
Table of contents:
- The Pains
- The Excuses
- The Solutions
The Pains
If you've worked on any project that is not 100% your own making, you've had plenty of problems due to outdated or lacking documentation. I don't mean to invoke those painful memories(feel free to skip ahead), but let's go through some of the more serious ones, for those that haven't shared in the joy of coding blind.
You're plopped into a project for the first time, and if you're lucky you have colleagues that have been here longer than you that can help guide you. And if you're born under a lucky star, they will have the patience to help you and documentation to point you too.
But, alas, most are not so lucky. Most likely you're thrown into the deep end by yourself. Alternatively, you're not alone but your colleagues are too busy drowning in the same mess. Lack of documentation means you're stabbing in the dark, breaking things more often than not, and regularly misinterpreting how the system works.
Your days are filled with reading logs and stack traces, putting var_dump($data);exit();s everywhere while you attempt to make heads or tails of the thing. By the end of the week you're exhausted and your TODO list isn't any shorter. This might sounds like a Legacy^tm problem, but it happens with young projects as well.
To make matters worse, you quickly become part of the problem. There are no "documentation guidelines" on the project, and you don't have time to be the first one to get the ball rolling. Instead, you rely on your own notes, spread across your notepad and .txt files. More often than not you go into the source code, 5 levels deep in the stack, to figure out how to fix minor spelling issues.
The day you figure out how to use CTRL+SHIFT+F(find in files) is the day you decide that you don't even need documentation, because you know your way around. And this becomes one of the many crutches you'll need to get by on the project.
The Excuses
Programmers tend to think of themselves as highly rational people. And this may very well be the case, but they take it a step too far, by rationalizing their mistakes and laziness, thus making it very hard to change their habits.
The favorite excuse (of us all, I might add) is:
"I comment my code well enough, I don't need extra documentation."
While it might be true that your code is the pinnacle of descriptiveness, the fact is that if you have to dive into the code to understand a feature you're already making a mistake. It makes sense to dive into the source to make estimates or understand the nuances of the process, but if you're looking at source code to understand a feature, you have a documentation problem. Now, dialing this excuse up to 11:
"My code is descriptive enough, I don't need documentation on top of it."
This can only be true if you're writing the simplest of CRUD apps. And even with CRUD apps there's a case to be made for proper docs. Additionally, you're not the only person needing the documentation. As the company grows the documentation will become useful to:
- Other developers
- QA testers
- Sales and Marketing
- You, 6 months after writing the feature
The list goes on, and the sooner you start writing docs, the less issues you'll have down the road.
"Sorry, we don't have time to write documentation, we move fast and break things!"
This is the same excuse used for the lack of writing unit tests, and in both cases the result of the new habit will save you time down the road. Sure, in the short term it seems like a waste of time, but it pays dividends as you go.
Not to mention that writing documentation takes comparably no time at all. I know, it feels like forever when you're writing documentation, but you're actually done within 30 minutes or less, for any single feature.
The only somewhat reasonable excuse to not write documentation is that the project is so small that it doesn't really need documentation. But here's a simple rule of thumb for your project size:
If it's worth building, it's worth documenting.
The Solutions
In a company with a development team of any meaningful size(ie, >0) you will come to know the joys of having a process. Whether you're a tester, a manager or a developer, you'll already know that a project needs some guidelines in place for the more "boring" work, so that more thought can be put into the "fun" work.
Document first, ask questions later.
I have to admit, when I got this idea, I thought it was revolutionary: along the lines of "Test Driven Development"; and that I was being super-clever by naming it "Documentation Driven Development". And then I did a quick Google search and realized that it's not a crazy new idea, and that people have been doing it for years(or decades, if you include "waterfall" based projects).
Alas, I'm not as smart as my mom thinks(sorry mom!), but I think the idea bears repeating. Before you dive into the code, write up the documentation.. And before you start rolling your eyes: yes, you can't get every detail right before getting to the code. But you can get the "story" right. You can get the "business value" and "usage patterns" right. There's a lot to gain:
- You get to jot down your thoughts, to flesh out the idea
- You get to run the documentation by other people, to make sure you understood the problem correctly
- You have a clear road-map of work involved, as well as a list of edge-cases and "nice-to-haves" for the future
- And with all of this you're fixing your documentation problem
Think about it like this. Nobody feels like writing documentation after the fact. Once you've banged out that big feature, you feel like grabbing a coffee and taking a break. But, if you have documentation ahead of the code, then suddenly you're writing it while the initial idea is still fresh.
The whole idea has a lot of overlap with TDD, which it also has a great synergy with.
That said, don't forget to document the changes and bug-fixes. If you don't do that as well, you're setting yourself up for documentation rot. It's a lot like technical debt, in that it will come back to bite you in the ass in the future.
As a bonus, start documenting every bigger post-mortem, describing how you discovered and fixed big problems at the project. This is a big topic on it's own.
Even if you already have a big project and no documentation, now's the time to start. Like Gandhi said, the only better time for starting documentation than today, is yesterday, or something along those lines. You start by documenting new features, and continue by documenting anything you touch or change. Much like with writing automated tests, and increasing your test coverage.
And before you know it, you'll have a great reference point for all of your team-mates, and maybe even your users! Who knows, if you do this correctly, you'll stop cussing out your past self, for being too lazy to write it.
Top comments (15)
Documentation has this nasty problem of becoming outdated. It can be infuriating to have stale documentation. It's often worse than having no separate documentation at all.
Docs should be left for high level things that don't change often, like the overall architecture, or module descriptions. I disagree with documenting individual files or classes. If you do, then it must be directly beside the code it's documenting (in the source code) to at least have a chance of being up-to-date.
If you're using docs as a design tool, then fine, but throw them away after it's been implemented.
Agreed 100%. That's why I propose documentation be updated before you write that new feature or update. More often then not, developers forget to update the documentation after the update's been pushed.
Also agreed! I guess it wasn't clear in the post but I didn't say you have to document every nook and cranny in the code. What I was saying, in the excuse section, was that documenting within the code is not a valid excuse to not have proper standalone documentation. In an ideal world you would have both good high-level documentation and accurate docblocks.
Couldn't agree more, the risk of refactored code linked to legacy comments is too high.
Always believed a summary doc block along with well named variables/method names should provide enough guidance for very little additional effort.
Although coming up with well named variables is another challenge in itself.
Doc blocks are mandatory, imho, but also a separate topic. The problem is that a lot of developers use the existence of docblocks and code comments as an excuse to not have to do non-code documentation.
I argue, in the post, that non-code documentation is also important, because it fills a different role than in-code documentation. Ideally you would have both!
I'm quite undecided. On most projects that had architecture docs, I was the person to write them. I never referred to them again, nor did anybody else.
I can see them being helpful should I disappear from a project, but I'm not convinced they are essential. They also take time, which is time not spent doing something else.
That's fair, I'd say it depends somewhat on the project. But also, fixing the knowledge silo is, long term, a thing worth doing for the project. That's an extra point I could add to the subject, thanks for that :)
Found the problem! Hehe ;)
How likely the docs are to be out of date or inaccurate is inversely proportional to how highly they are prioritized by the people who are changing things to be documented.
But, one size does not fit all.
The important takeaway from Nick's article is to make documentation a conscious design decision instead of a default (or ignored) one. Understand and decide for what you will need documentation and why, and then act on those decisions. Know to whom you need to communicate, what they need to know and why, and the best way to communicate that to them.
I've been in a project , and after finished , had to make all docs from beginning..
It was pain..
I think documentations should evolve as project is growing.. i mean for example
Documentation should be part of adding/modifying a feature and if a dev mark a feature as completed without documented that along the code implements that , should never accepted.
P.S if anyone has to suggest quick tools for small documentations , please share :)
I typically meet with my team to plan our solutions and then we take notes of some.l decisions like interfaces, patterns, data structures and such. I'll try to write it down in a cohesive way next time and push as documentation. Sounds good.
That's already better than what most do, so you have a head start! There's always more you could be doing of course, it's just that making it a required step in the process will keep you more consistent at it. Thanks for sharing your experience!
You made a well presented case for making the effort to write documentation. You even compelled me to add more documentation writing into my process.
Thank you for the feedback!
Hello, thank you for the post, could you please share what tools you recommend for documenting?
do you use chart? could you share an example?😄
Hey, glad it could be useful!
We use Markdown for writing documentation. Recently started moving to Confluence, but there are good free tools out there as well. For charts, I use draw.io and export to PNG.