So would I kid, you got any?

We're about to launch the next version of CSV Manager. It's coming out Real Soon Now.

The thing is, I'm pretty much obsessed with having really high-quality API documentation. I mean, most Java API documentation is really tragic. One liners, out-of-date, misspellings, rotten links, no context. All that sort of evil stuff.

I want Ricebridge documentation to be different. But by God, it's hard. Writing good API documentation is the most difficult thing I ever done. It's not technically difficult, it's psychologically difficult. You see, every item of text has to be context-independent. You have to be able to jump into the API docs at any point and get pretty much all the information you need, or find links to it at least. That means that each item of documentation is highly repetitive and must contain lots of redundancy. This is what makes the API documentation "good". You can always find out what you need to know right away, right where you are.

But it makes it a right royal pain to write. A major major job. But I think it's worth it. It's a differentiator, to go all business-speak on you. It's part of what makes Ricebridge components different. We don't answer support questions by saying "go ask in the forums, and you might get an answer..." Documentation, which you pay for, is where you should find what you need.

Are we there yet? No way. We're not even 10%. But I do know we're a lot better than most. We care, at least.

It's very frustrating though, because I don't know how to do it better. Writing good API documentation just seems to be hard problem. You can't outsource it easily. Only the person who wrote the code really understands it. You can't just dump a lot of text on someone and expect them to "make it better". You need someone who has domain knowledge. And there just aren't that many copywriters out there who know enough about Java.

I don't mean to dump on copywriters in general by the way, but I've just seen far too much software documentation that was obviously written by someone who was not given sufficient technical support. It's unfair on the copywriter as well. I want to be specific about this problem. I 'm not taking about user manuals or introductory guides or even reference material. I'm taking about hard-core technical documentation for developers. Our products do not have a GUI, so the only way you can even understand how they work is to program with them. If you can't program, you can't even experience them, which seems essential for writing about them.

I don't know. Am I being to hard? Too stuck in my box? If you reckon you're a dab hand at writing Java API documentation and you're freelance, drop me a line and we'll look you up the next time. I am willing to try.

So in the meantime we soldier on and I have to write it myself. It actually takes longer than the coding. No it really does. But you know what, I'm proud of the results and every single customer loves our documentation, so we'll stick with it.