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.

Original article: Open Source Tech Writer

In the past I read about the value of something being a function of the quality of the idea and the quality of execution. This makes a lot of sense to me. You can have the greatest idea in the whole world, but without effort and execution, there is no value. Even a medium quality idea done moderately well is useful.

I have about five hundred ideas right now. Some of them are pretty good, some are a little questionable, some old, some recent. Unfortunately, I am currently making $0.00 (that exchanges to 0.00 Euros) off of those ideas. That’s $0.00 worth of value that has been created by these written down ideas. They certainly give me a sense of excitement when I look at them, so I guess they’re worth something. I look back in fond admiration, and still think they’re pretty good. Hmm… maybe I’m attached.

But like the day when I sadly realized that I could never know everything there was to know, I have come to accept the idea that I will never have the time or energy to implement every idea that I have, even if (or perhaps, especially if) they are all five-star ideas. It wasn’t easy to accept.

Steve Yegge realized one day that he only had so many projects left in his life. He writes really long posts, so I’ll give a short quote from Rich Programmer Food, which is about why knowing about compilers is good for you:

Unfortunately, writing a compiler creates a living thing. I didn’t realize this going into it. I wasn’t asking for a baby. It was a complete surprise to me, after 20-odd years of industry experience, that even writing a simple interpreter would produce a lifetime of work.

Go figure.

I credit the phrase “a lifetime of work” to Bob Jervis, a friend of mine who happens to be the original author of Turbo C (with which I myself learned to program), and a damn good, even world-class compiler writer.

He gave a tech talk recently (Google does that a LOT) in which he pointed out that even just the set of features the audience had asked for was a lifetime of work.

This phrasing resonated deeply with me. It was similar to my realization about 18 months back that I only have a small finite number of 5-year projects left, and I have to start choosing them very carefully. After writing my own “production interpreter”, I realized that the work remaining was unbounded.

I mean it. Unbounded.

So from one perspective, I suppose I should just release what I’ve got and start marketing it, so other people will jump on board and start helping out. On the other hand, I started this particular side-project not to create a lifetime of work for myself (far from it), but to make sure I knew enough about compilers to be able to rant semi-intelligently about them, after a few glasses of wine, to a quarter million readers.

Sometimes ideas are ahead of their time by a couple of weeks or a couple of years. Sometimes they just aren’t expressed in the right way to the right people the first time. But you can’t give up if you believe in the idea. And it’s a lot easier to get traction for something when you start working on it.

What I’m trying to say here is that seeing a solution to a problem is not going to make a difference in the world. Applying your efforts and making your voice heard to make that solution a reality can. And even if you don’t succeed, if you’re smart you will learn how to do it better next time, and you may find something more valuable along the way.

Original article: What an idea is worth