Documentation is Always the Hardest Part

This post was originally part of a series documenting an open source web framework I worked on. The framework is well and dead, but I’m keeping these posts for posterity.

I’ve pretty much wrapped up the coding for the next version of Frame2, and decided to give the documentation a once-over. All in all, it’s not too bad, but it’s not great either. There’s some real improvements that can be made, but I don’t see it happening any time soon.

Don’t get me wrong — I don’t mind writing doc. One of the most annoying things is to download some open source project and not have any idea how to use it. The issue I have with writing doc is that the feedback loop is entirely different than for code. When writing code with automated tests, there’s immediate feedback if you’ve done the right thing or not. With doc, I have to wait for someone to actually read the doc and give me feedback. This is frustrating because: 1) I don’t know if anybody even uses Frame2, 2) of the people that do use it, I don’t know if they read the doc, and 3) if the doc sucks, does anybody care enough to tell me?

So, for now I’ve corrected obvious errors in the doc, but I haven’t added anything. I’ve started a list of things to cover, but I don’t know when I’ll get to them. Third party dependencies need to be explained better, and web services interaction needs a LOT of coverage.

I feel that the getting started guides and the example applications are sufficient to get somebody up and running with a basic Frame2 application. If I’m wrong, hopefully somebody will let me know!