I've written two posts so far about how to do open development work.  

The first piece set forth two rules: 1. All meetings must be open and 2. Ratify defacto standards if all posible. 

The second piece explained how to use open formats, introducing three rules: 3. If it hurts when you do it, stop doing it. 4. Shut up and eat your vegetables. 5. Assume people have common sense. 

In this piece, I introduce a new rule: 6. Design and document only your wire format, do not depend on toolkits to hide the complexity. 

First a little background... In what we may come to look at as the golden age of the web, you could always do a View Source on a page and see how it was put together. HTML, back then, was simple enough so that even a technical neophyte could figure it out, if they had the IQ and tenacity. You didn't need years of experience programming to figure it out. This was important! It's what made it possible for the web to grow like weed. 

When I was coming up as a programmer in the 1970s, you needed a lot of experience to work in the world of minis and mainframes. The programmers of the previous generation felt secure that in order to make real software you had to understand all that they understood, which assured them a place at the top of the ladder, and made young dudes like me start out at the bottom. Heh. This is always a mistake. If you've created too complex a world, the next generation will just create a new one that's simpler. One that they understand and you don't. You're still at the top of a ladder -- your ladder. They just created a new one, and you're not even on it.  

This was the danger, by the way, of making XML too complicated. With all the WS's that Microsoft, Sun and IBM added (and a dozen other smaller companies). I lobbied hard against it, you can find it all here in the archive on scripting.com, but they went ahead. And that begat JSON, which is simpler than XML mostly in that it doesn't (yet) have all that cruft. But if you want to do something real with JSON, there are a lot of services to master, and more all the time. 

The enemy of progress in tech is complexity. The more unnecessary complexity that's added (and the WS layer on XML is a perfect example of unnecessary-ness) the sooner new development will stop, as the incentives to reinvent go up. 

One way groups try to side-step creeping complexity is to create toolkits that hide it behind APIs. They implement the toolkits for the top five development environments (or six or seven, some but not all). They reason that this catches most of the developers. Maybe it does. But maybe the next layer is going to come from a language you never heard of. For example, the minicomputer guys, if they ever heard of Unix, probably thought of it as a toy operating system. They wouldn't have made a toolkit for that platform. Yet it was one of the primary successors. In other words, if you're the guy grappling with complexity, your head is probably too deeply buried in the ways of the past to see the future coming. You're going to leave out the guys you most need to not leave out.  

Another reason the no-toolkits approach is important is that it puts your dirty laundry out there for everyone to see. If you have any pride, you may want to clean it up and simplify before you show it to the world. Somehow, seeing it through other people's eyes gives you a perspective that makes simplifications visible when they weren't before. Every bit of complexity that's left in will give some future programmer an incentive to reinvent your ass.  

Don't get me wrong -- it's good to have toolkits. They should be listed on the site. But the primary documentation must be written for developers who are programming right on the wire, without any toolkits in the way.  

PS: Hat-tip to Joel Spolsky's Architecture Astronauts.