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.