Why you need documentation (Wherein I reveal my distrust of tech writers)

Posted On September 22, 2015

Do you really need to document everything?

Those who say that there is no such thing as a stupid question might be reconsidering their position right about now. Of course we need to document everything!

Perhaps my reluctance stems from my hatred of technical writers. If you are a tech writer and are a decent human being, the next time we are at the same event, please come up and introduce yourself. I would like to see what you look like. All of the technical writers I ever knew well were  evil, which made me suspicious of the rest of you. I should also note here that if you respond to this by posting hateful comments you will have only reinforced the stereotype of tech writers = evil.

Supposedly, tech writers are hired because of their ability to communicate well, which makes me wonder why they insist on making such insulting comments as:

I translate what the programmers wrote into English so the normal people can understand it.

or

I take what the engineers say and put it into complete sentences.

or

Everyone knows that software engineers can’t communicate with other humans.

Hey, tech writers, you do know we’re standing right here and we can hear you, right?

Animosity toward an entire semi-profession aside, I caught myself wondering how much documentation was really necessary. I was looking through some code I had written months before, which, I have to confess had almost no comments in the code and no documentation anywhere outside of the code. Even though I hadn’t looked at it in four months (there was a comment with the date created!), I found it pretty easy to read and got to thinking that perhaps documentation was over-sold by literature majors who couldn’t find jobs.

Then, an uncharacteristic burst of rationality overtook me and I realized that our company is growing. The code was pretty clear to me because I’m fairly familiar with the canvas tag and using canvas for graphics. The program used two libraries with which I’m familiar – jquery and a library for making charts. There were 50 other ways the program was easy for me to read because I wrote it using what was easy and familiar for me. However, we’re a growing company, and as The Invisible Developer reminded me, whether it happens kicking and screaming or I go quietly, the handwriting is on the wall and I’m going to be doing less coding and more CEO’ing.

I know that if HE were to have taken the same program, there would be much swearing going on upstairs right now.

So, yes, documentation appears to be more necessary than originally believed.

Is the solution for me to go through and document everything? Sigh. If only I had infinite time.

What I think might work and be a good idea for a new employee is to have him or her start off with reading some of the code and documenting it. That would be a good way to get familiar with what we are doing before diving into a project. It would also be a good way for us to verify if that person understands what is going on in a particular piece of code.

Or, one might say that was a lazy way for me to get out of writing documentation – if one were a tech writer.

 

---

My ISP is currently not allowing me to upload or insert image files. Show your sympathy for me by buying games. The games will make you smarter, amuse you and enable me to afford a better host. Everyone wins!