Writing documentation is the worst thing ever

I hate writing documentation. It’s one of those things that’s awful to do, and it’s awful when you don’t have it.

Being a developer, it’s double icky (technical term).  In the first part, I hate writing it. It’s time consuming, it’s a pain to keep up to date, it’s hard to write good documentation, etc, etc.  On the other hand, as a developer, I use a lot of other people’s code.  When I do that, I want to be able to use it as fast as I can, and get on with my life. So I really hate it when the documentation is trash.  It makes my job harder, and things take longer.

I’m in the midst of this cycle now.  At work I’m creating an API that I won’t be directly using, so the documentation is aimed at our other developers.  It has to be accurate, and let them move rapidly.  It’s a giant pain.

I’ve been researching ways to make it easier for me, and better for them.  Take a moment to appreciate the irony (or whatever it is). I’m looking for a library to help me make documentation easier, so it also has to have good documentation.  DOCUMENTATION-CEPTION *bwwwaaarrrrr*.

I’ve mostly settled on apipie. It’s does a decent job of getting out of my way, as the code for the documentation (it’s a documentation generator, essentially) lives right next to the code it pertains to.  It also can serve the documentation up to consumers along side your application, which is nice, although we won’t use it like that.

For all that, I still hate it.  I wish that computers were smart enough, or that somebody had made them smart enough to just look at my code, and make some documentation. I don’t care if it did everything but write nice descriptions about parameters and junk.  If it just put it in a framework that I could add the nice english into, and kept it up to date, I’d be so happy.

I might even pay for it.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s