|

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

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!

 

Similar Posts

One Comment

  1. Doc, I always see you as this everyday, regular mom, who has an alter ego in the form of a super hero…I am such a big fan of yours because, you, like me are a perfectionist. The only difference is you are extremely modest about it. You see a challenge and you have to be perfect at it. Right now you may be that modest person and say ‘I strongly disagree with that statement’ but in your heart of hearts you probably do the exact same thing as me..You see a challenge and you want to take on every single aspect of said challenge. As impossible as it is you want to say ‘I got this guys!’ I realize your probably wondering where all of this rambling is going..Well my point is this, you are CEO of a company that is expanding, so as much as you want to be that super woman who can tackle all aspects you have to realize that what you said about CEOing is inevitable..But I, being a perfectionist myself, know and understand you don’t want to lay down that proverbial sword,it’s not what you do!! LoL But even I learned we all need others, as evil as they might seem, from time to time. This is why I think you look at these tech writers and want to hate them..Because they are doing a job that you think, in your heart, can do by yourself. You are a super woman Doc but sometimes you have to fold your cape up and be,Oh No!!, regular..LoL. Thank you for listening to my rant,
    Your number one fan
    Matt

Leave a Reply

Your email address will not be published. Required fields are marked *