Open Source Tech Writer
A majority of open source projects have a paucity of documentation. However, they still have value as a working system. I argue that improving the documentation of a codebase intended for general use is one of the highest value activities that a developer can do. Although documentation may not be directly contributing to the codebase, the writer provides a valuable service by understanding the code and imparting that knowledge to others.
I would go so far as to say that there should be open source technical writers. They look for interesting projects to write basic documentation for. While there are a smattering of tutorials for certain frameworks, they are not condensed, are not authoritative, and are often misleading because of changes to the framework or convoluted examples. When the core developers move at the speed of the forum or even IRC, it’s tough for a new person to have anywhere near that amount of knowledge. A centralized wiki with pertinent and up-to-date examples is quite useful.
If you are not yet a badass developer, this kind of project aids you in three ways. First, you gain experience looking at unfamiliar code bases and reasoning about them. This is especially helpful if you maintain code, and also assists you in writing more maintainable code. Second, you get some street cred for being closely involved with the developers on the project and working with them. You’re likely to learn something from the alpha geeks and advance your skills. Third, your writing skills improve, which helps you out in many areas over the long run.
In a nutshell, the kind of people who are building their own system or framework are generally not obsessed with documenting for average people. This could be due to time constraints or general personality traits. But the value that they create is wasted if people are not comfortable interacting with it.
Clojure
There is an interesting thread on the Clojure discussion group about making examples readable and general ways to help developers who are new to the language and want to code idiomatically. One post mentioned the Clojure page on concurrency. If you can read through the example code there and want to tackle concurrency (which is supposed to be a strength of Clojure), then I applaud you. This isn’t a knock against Clojure, it’s just so new that most everyone who’s interested has been playing around with it and trying to understand it better.
One of the most important points in the post is that to get a community rallied around a language or framework, it’s necessary to have good documentation so people aren’t put off by it. The Clojure folks are getting there, as there are a couple of wikis around that people dump stuff into.
qooxdoo
The qooxdoo framework illustrates one of my favorite examples of excellent open source documentation. When I first started looking at it, I was impressed by the amount of examples, pictures, screenshots that were included. The manual is rife with examples and code snippets.
They have a huge demo area that shows how simple effects can be created using at it. Looking at these demos, I started visualizing about how exciting it would be to work with this framework. As another great demo, it has an API documentation viewer, which itself is written with qooxdoo. It must have taken time to generate all of this…
Parting thoughts
On the other hand, one could argue that with a nascent open-source product, having too many people involved early is problematic for direction and quality density. Also, the people who create code which uses the product will constantly have to change their code because the underlying architecture or best practices change. It’s the bleeding part of the bleeding edge.
I’m not saying that I’m committing to doing any of this… 
Just thought that this was an interesting line of thinking.
next post: Software as a Sitcom
Hi Anthony, congrats for that fine blog post, I think all your points are valid.
Referring to qooxdoo as one of your “favorite examples of excellent open source documentation” came as quite a surprise.
We usually tend to think there’s still tons to add, fix and polish. Thanks anyway, I believe your statement does indeed motivate us to further improve documentation.
I agree with the premise behind this article. This is a good read. I’ve often thought that the documentation in Open Source projects is lacking as well. I think we should all follow php.net’s lead as their documentation is the best of any (closed source or open).
With php.net you type in php.net/function_name and it will give you documentation on that function, documentation on related functions, user comments, caveats, etc.
It’s awesome. I wish JavaScript, C++, Perl, Python, Java, and all the other languages had this sort of thing. If you know of a similar site for other languages, can you share it??
I’ve often thought that documenting open source projects is a huge opportunity for the freelance tech writer.
It would fulfill a need (for the information) and help the writer gain recognition.
Just creating a simple site with Docbook -> HTML would get huge amounts of traffic. The writer could earn a significant amount from ads and anything that gets a lot of traction could get published on paper. It would have a demonstrated audience.
Thanks for the comments! I thought maybe I was the only one.
I was kind of vague on the qooxdoo framework in the original post, so I put in some more details about why I thought it was nice. I had a small conversation outside of the blog with Andreas. It was interesting to formalize why I thought that it was an appealingly documented framework. I learned a lot. I would say that there are likely objective criteria, and you can probably measure your success at least partially by metrics (how many downloads, new users, questions asked, etc.) It was interesting how the most used pages were the best, in that poor sentences were likely selected against. I think there’s an interesting thought around here with evolution of documentation. Kind of like forces tend to make documentation smoother in the spots where it is rough, like a river.
John:
I agree that PHP’s documentation was helpful when I worked with it. I liked the format of
1) very general description
2) method signature
3) argument explanation
4) detailed examples
5) user thoughts/suggestions
To my memory, a lot of times the user comments were helpful because they said something like, “don’t do it this way because this is insecure.” As of yet, I don’t know of a single place that you can look for documentation, it seems like it varies. I smell an opportunity.
One thing that would be helpful is just to get some consistency. I mean, Java documentation typically looks very much different from .net documentation. If you know where something is and where to look for it, that can be quite helpful. Although to be fair, perhaps the kind of documentation that works for Java won’t work for Ruby on Rails, and vice versa. Perhaps it comes down to knowing your audience? (as writing should)
To Paul:
Glad that you agree. What better way to practice your skills in communicating and writing than working on something you find enjoyable and challenging? I think that the Pragmatic Programmers to some degree are doing this with languages like Clojure, Ruby on Rails, etc. They try to find a new shiny thing (language/framework/tool) and then make a book like people are used to seeing. This definitely helps popularize the shiny thing.
I concur that doing a test run or gauging the popularity is important if you want to make sure your efforts are useful. It seems like some of the Perl books are just formalizations of FAQs that are out there, but perhaps that only seemed to be the case because I was reading it after the FAQs and the books had coalesced on subject matter.
Of course, for the sake of the environment, think about eBooks or PDFs!
Plus, you’ll probably get more margin by doing this due to less overhead of printing.
Thanks again for the comments guys, they were very thoughtful.