Improving software through better documentation

Of course everyone who's ever worked with a third-party tool should be familiar with "that project that's not well documented". It's a common problem, we've all dealt with it, and it's pretty universally challenging. Rarely is there a tool so simple and so intuitive that it can become ubiquitous without some kind of documentation. It goes without saying that people consider thorough documentation a crucial requirement for software projects.

On the other side of the coin, anyone who's ever worked on an open source project will generally vouch for the difficulty in documenting them. For those of us who contribute to open source projects it's often a challenge to contribute the code to begin with and then documenting it frequently becomes that "finishing touch" that you can't seem to find the time to complete. Doug Huges says "The documentation in Reactor needs a lot of love. It's a fact." In his blog about the future of Reactor he said this:

So, what's the cause of this? In a nutshell: me. The rise and stall of Reactor corresponded with the Rise and (thus far) success of Alagad. I can not manage both the demands of developing, documenting and supporting Reactor while also growing Alagad.

And that's not even getting into the issues I've mentioned before about being too familiar with the solution.

But it's not enough that the documentation be thorough, it also needs to be concise. It's ironic if not an oxy-moron, but it's true. The same challenges that we face writing documentation are faced by the people who will read it. We only have so many hours in the day and so often the things we want to learn don't make it into a given day's workload. I know I have an ever growing list of things to tackle. How big is your list? How big was it yesterday? How big was it last week? How big will it be tomorrow?

Over the years I've heard a variety of comments about my documentation. They've ranged from Ben Nadel's recent complement that "I have never felt that your answers or explanations lacked anything. You seem to be very thorough." to others complaining about a lack of comments in my code. Everyone's standards are different of course and the YMMV adage always applies.

Judith Dinowitz, the editor of Fusion Authority and the FAQU, considers me to be an excellent writer. But even being described as an "excellent writer", an article doesn't go to press for FAQU without a good bit of revision and editing and fact-checking. That's a whole additional layer involved in writing "professional documentation" that's often just not there with open source projects despite our best efforts because we're doing well enough to document them in the first place.

Honestly I feel that the lack of that extra layer of editorial review in my own documentation is a real challenge for me specifically. This stems from the fact that I have a condition called Asperger Syndrome. This is an autistm spectrum disorder (ASD) which alters the way in which the brain processes information. Sensory information is particularly affected and it causes things like "hyperfocus" where we get "into the zone" in such a way that it often takes my girlfriend several attempts to get my attention even though she's in the same room!

Although I don't read very quickly at all (never got the hang of speed reading or skimming), this does allow me to focus on a single task more effectively. It just makes me harder to interrupt when I'm doing it. (Try these exercises to find out how counterproductive multitasking is.) This also helps me to digest very dense content fairly quickly and as some of my autistic friends have described, when I'm learning something new I tend to try and absorb as much of it as I can in a very short period of time.

This also means that I may tend to gravitate toward sources of content that are somewhat dense. And I may tend to write things that are... dense... The problem of course lies in that "your mileage may vary" thing. The content that works well for me is often not the content that works well for others. In spite of the complement from Ben Nadel, there's been an ongoing theme for me over the years of people making comments about my writing being overtly verbose. Just the other day Adam Tuttle described my Galleon Forums Project report as a "wall of text" and made the comment that I'd piqued his interest in the onTap framework... if only I could "figure out how to squeeze another 6 or 7 hours into every day" so he'd have time to check it out.

Several years ago I met Jeff Peters at the Fusebox / Frameworks convention in DC and during that conversation he related a story of having looked at the framework with a friend and I heard the phrase "do I have to read ALL this?!" That was a much earlier version of the framework and I think it wasn't until after that when I finally created a "Quick Start" guide inspired by Joe Rinehart's quick-start for Model-Glue. Kay Smoljak's recent interview for the SitePoint blog was done via a Google document and Kay graciously commented that I should publish the entire contents of the interview somewhere else because it was far too long for her blog and that she felt she had to cut some content she enjoyed. I think she did an excellent job of editing, but the underlying message from all these sources over the years is pretty clear: TOO MUCH.

As I mentioned before, just as those of us working on open source projects lament not having time to write documentation, it can be a challenge for others to find the time to read it. Which means that my naturally verbose style is probably not the best style to help people learn a new software architecture. I suspect this is one of the larger reasons why there's been little adoption of the onTap framework in previous years. One of the other reasons is that like a lot of autistic people I find it challenging to network and I'm working on that also. These are among a variety of reasons why I'm actively seeking both an evangelist for the project and a technical writer. I will continue to do these things to the best of my ability and I welcome and appreciate all the great feedback I'm getting. Hopefully soon these roles will be filled by people who have a better natural aptitude for them. :)

I'm preparing for an interview with Brian Meloche for the CFConversations podcast. Brian has been very gracious in helping me out by providing a set of questions for me, again via Google docs, in advance of the podcast to help me prepare my answers. I added some answers and got a quick response from Brian saying "this is too much to cover in a 30-45 minute podcast". So we're working on helping me dial-in my responses.

I've come to understand that I need a LOT of preparation (and feedback) for a given subject before I have a good handle on how to present a good "introduction" for others. Part of the problem is that I have a difficult time understanding what elements of a story others will relate to and will feel are "good to know" in a short time span. For that matter just plain writing, although I do it a lot, is something of a struggle for me. I usually want to include a lot of "side notes", that's one challenge. Another challenge is organizing it into a logical flow that makes sense to others and doesn't leave them wondering how I came to a particular conclusion. Even something as simple as knowing where to break paragraphs is difficult for me. When is it a complete thought? How long is too long? Should I just go read the Strunk and White manual?

This is something I continue to work on. I'm also working on finding new ways to express concepts so that I can give people better "thumbnail" synopsis of ideas. I'm not good at synopsis, but hopefully I'm getting better. :) This has been made especially clear to me by some recent feedback on the framework documentation. One pretty thorough comment on the blog here helped me to revise the overview page of the documentation and I realized that the original "overview" was very bad. The new overview has also made its way to the Project Goals page of the wiki. And just last week or so I also had a brief eureka moment when I was able to piece together the virtual private application (VPA) analogy.

Thanks to everyone for all the great feedback that helps me improve. :)

Virtual Private Applications (VPA)

One of the things that I've traditionally found difficult to explain is the business case for the "branding features" in the onTap framework. So when this analogy hit me the other day I was pretty excited to have a simple explanation. Using the onTap framework, a branded application is a lot like a Virtual Private Server (VPS) for hosting. A VPS is a stable, scalable, low-cost alternative to dedicated hosting. A VPA is a stable, scalable, low-cost alternative to unique custom applications.

So I've created a page in the wiki that describes the forces involved in the problem and how a Virtual Private Application (VPA) resolves many of those problems. I even added a couple comic strips. :)

P.S. Editing help is much appreciated. :)

fixed database tag docs

Just uploaded a new build. Docs for some of the custom tags in the /dba/ tag library were broken due to pointing at the wrong file name.

BlogCFC was created by Raymond Camden. This blog is running version 5.5.006. | Protected by Akismet | Blog with WordPress