Personal Writing Philosophy
As a hard core software engineer who shares many of the same values and interests in technology as my peers, I'm a sort of odd bird as I enjoy sitting in front of my editor writing documentation. As the majority of my fellow "geeks" run for the hills when they see the dreaded task on their project breakdown, I secretly crave the allocated time to articulate my hard work to the world.
As I've grown in my discipline over the years, I've gained a fond appreciation for not only the value of exceptional content, but also in how it is presented and communicated. The documentation artifacts produced by many software engineers clearly express their disdain for the exercise, and if you've ever had to read them you would probably agree it is exercise. The content insinuates existence of content for content's sake without the consideration of an individual new to the domain relying on the text to climb a learning curve or familiarize themselves with essential knowledge. The substance (or perhaps lack of) has little to no continuity in flow and fails to set or boldly assumes prior knowledge of context. And, unfortunately that is often times the missing key to success in many a learning environment: context. Say it again with me: CONTEXT!
Another attribute of online documentation is voice and expression. Again I'm compelled to parenthesize lack of, but I am making concerted efforts to avoid parenthesized comments in my writing (however tempting it may be). I should mention personality and humor here, but more on that in a moment. As is stated in Ecclesiastes, there is a time for everything. In writing, there is a time for active and passive voice, formal and informal, normative and non-normative, and so on. I've read literally hundreds of technical docs, online manuals, and full blown books on a number of technical subjects. Of these, I've found the ones I tend to enjoy and retain the most information from are those that speak informally with a mixture of the author's personality and humor. Most of my online documentation adheres to a formal writing style, but for many texts I have chosen to follow in the footsteps of my favorite technical authors.