Oh documentation writing, how almost nobody likes you.
I’m going through this now as I prepare to release an update to Sports Bench, my WordPress sports plugin/theme package. It’s a pretty big update with a number of new functions that need to be documented for users so they can troubleshoot or extend it to meet their needs.
But even as a writer, it’s not really all that fun.
For starters, it’s a lot of repetitive work, repeating the same process of typing up the function description, parameters, return value and where it is in the code. Fortunately for me, being more of a natural writer, this isn’t necessary difficult; just time consuming and boring. But for non-writer developers, it can be a challenge.
That being said, documentation is an important part of all programming projects. Every project, no matter how big or how small, has some documentation. And even if the project you’re working on is a solo project, you should definitely be writing documentation for it.
Helps others understand your program or project
The number one goal for documentation in programming project is to help others understand what’s going on. Whether it’s other members on a team or someone else who’s using the program, plain words are needed to explain what’s happening in the program and how to use it.
Even as an experience programmer, it takes me a lot of time to comb through code to understand what’s going on. Sure, I know the syntax and how programs work, but it takes a while to understand. Code can be very confusing, especially if it’s in a different style than what I’m used to.
But documentation provides a chance to explain what’s going on in the code in regular words. You can say what functions are doing what, how classes are going to be used and many other things that will be helpful for others. And whether its just a doc block before a function or class or a separate page with documentation, that’s a massive help.
If you want others to be able to use your program or project, documentation is a must.
Helps you understand your program or project
But writing documentation can also have the same effect on you as well. Because you’re having to go through code and document all of the functions and processes going on the program, you also get a deeper understanding of what’s going on with your program.
It might seem a bit odd at first. After all, you wrote the code didn’t you? You should know everything about it anyway, right?
Well not always. Our memories are a fickle thing sometime and you’re not always going to remember every single thing about your program. So going through the code again and documenting everything will help jog your memory and solidify that knowledge in your brain.
Makes debugging and figuring out issues easier
Finally, all of this leads up to making it so much easier to figure out problems and to debug if something does go wrong.
Think about it. If you know the code base pretty well and the user or other people can find out the information about the code base easily, it makes figuring out solutions to problems quicker.
If a function isn’t working, you can easily find where it is in the code and see what might be going wrong. Or if the problem comes from another function that’s being used, you can connect the dots pretty quickly. And quicker debugging means a happier time for you and whoever is using your code or program.
So I know it can pretty difficult and/or tedious to write documentation for a project, especially a large one. Trust me, I just wrote/rewrote documentation for over 200 functions and filters for Sports Bench. It took a week, and it wasn’t fun.
But that work is going to pay off in the end. And it will make your life and your users’ lives easier. So do it.