If it's worth figuring out, it's worth writing down

Full article

The hardest part of programming is not writing code. That's the fun part, when you let loose the creative side and make things. It might get ugly, it might need torn down and rebuilt a few times, it might need to be set aside for awhile - but that drive to create something is what keeps us coming back.

We don't write code in a silo though. Every line written affects what came before it and what (eventually) comes after it. You might be providing the foundation for 20 more layers and setting the standard (even unwittingly) for years to come. You might discover a pattern in the code, which no one ever told you about and certainly isn't documented anywhere, but it works. Or you might just be adding one more piece to the puzzle of a large system, and find yourself having to understand all the pieces around it first.

Whatever the case, you're likely to spend a lot more time reading and discerning code than actually writing it. And the last person who touched the area of code your changing had to do the same. And the next person will again. Most of us have been in the same position as this guy, right down to the last frame. Even a small amount of documentation somewhere, anywhere would've helped you... and it will help the next person. (Which ironically might be you 6 months from now.)

Programming for Non-Programmers - PHD Comics

If you're thinking, well I don't have anywhere to store documentation, literally anywhere is better than nowhere. Pick whatever is secure, searchable, sharable, and within arm's reach.

Although personally I've used confluence, joplin, various wikis, etc., the current setup at work is an office365 environment that our whole team can view. It's basically like google docs if you're more familiar with that, with a folder structure, support for the standard document types, and fully indexed. Nothing too fancy.

How do we organize it? There's a folder to hold project-related info, others that are more application-centric, and still others to hold notes about the infrastructure that provides the backbones of all our applications.

What's in there? Anything. Whatever. There's word documents that explain how areas of the system are setup (à la readme files), flowcharts to show system interactions, and links to external documentation. I've even noted sql queries and test scenarios that helped during testing, because the next time someone requests a new feature, we may need them again. If no one needs it, nothing lost.

If they do though, that one piece of documentation you wrote may be just what they need to find their way through a murky bit of code.

And if you're thinking, I don't have time to write documentation, that's silly. You're already spending time figuring things out, probably scribbling notes and flow charts all over a notebook. What's it take to organize your thoughts a bit and write it out?

Communicating effectively is as challenging as ever. More of us (in this field anyway) are working remotely than ever before, and we don't have the luxury of just sitting down next to the last person who touched the code. If nothing else, try to look at it as learning a new skill.. one that your team will be grateful for and that companies value.

Author

Grant Winney

I write when I've got something to share - a personal project, a solution to a difficult problem, or just an idea. We learn by doing and sharing. We've all got something to contribute.


Comments / Reactions