Documentation Isn’t a Chore. Its a Tool.

Documentation as a Chore

Documentation is viewed of as an “after thought” in a lot of software development teams — though we get angry when a third-party library treated it the same way. No one wants to write it, review, keep it up to date. We view it as a chore we have to do. In fact, if your a developer, you’ve liked rolled your eyes once or twice at me brining it up.

Documentation as as Tool

I think if we can embrace documentation as a tool, it can help us write better software.

Having Documentation Means Easier Coding

So, I followed DeHaan’s advice. Instead of spending hours and hours trying to keep things straight in my head as I hacking away at my module.py script, I spent hours and hours writing documentation in a README.md file. Not the most exciting thing in the world, but I got through it.

Lets Not Get Carried Away Though…

I’m not suggesting the every project needs to do this to the same level I did — you might likely never start if you had to write documentation to answer everything about your software and is one of the reasons the Agile Manifesto calls out “working software over comprehensive documentation”. However, I think that my experience showed me that treating documentation as a first-class software artifact can help you write better code. And for those of you thinking “just write self-documenting code”, I totally agree that you should aim for that. I just also know that the idea of self-documenting code is viewed more of as a style and fall-back measure than treating documentation as a vital part of healthy software systems.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Dan Goslen

Dan Goslen

1.7K Followers

Jesus follower | husband | IJM advocate | software engineer. I share tips and tools for building software as a team!