Blue Sky On Mars

Thoughts on Building Software Products
September 27, 2005

What I want in a Wiki for software development

by Kevin Dangoor

There are lots of wiki programs out there. I mean lots. It seems like everyone has written one, in just about every language there is.

Wikis are used a lot for software project documentation, because they’re just so easy. The barriers to jumping into a wiki and adding a page where one seems needed are so low that people dive right in with gusto. You’d think that my issue with wikis is that you end up with a huge mass of disorganized pages. That’s not it, though… with some judicious care, that mass can be turned into something useful readily enough.

My issue with wikis for software development is a problem of unknown obsolescence. The best example of this I can highlight right now is the CherryPy wiki. There’s quite a bit of potentially useful material there, but almost all of it won’t work as written in CherryPy 2.1. You go to the wiki looking for info, and you have no idea when you see a given page whether it’s applicable for the version of the software you’re using.

TurboGears documentation is all in Subversion because of this. This allows the documentation to naturally be tied to the version of the software. This also has the advantage that I can use my favorite editor and take full advantage of HTML when I’m doing docs.

Unfortunately, though, I don’t think anyone is going to check out the project just to write up some new docs. People are a lot more likely to add documentation if it’s as easy to do as updating a wiki.

We could try to give wikis branching and merging capabilities like you find in source control systems. We could also require users to go through a root canal to view our docs and see how well that goes over. Even though tools have gotten better than they were, branching and merging still seems to be a black art for many.

Perhaps there’s a simplified user interface that will do the trick. Something like this:

  • By default, a user will be browsing at the latest released version (something that is marked by an admin). Links at the top of the page will let the user choose a different version to browse.
  • Only major versions would get their own version of the wiki. In most software projects, the difference between 2.0 and 2.0.1 doesn’t involve a whole bunch of potentially breaking changes.
  • When a new version is created, the wiki starts out empty. This is important, because it needs to be very clear to someone when they may be viewing a page that is out of date.
  • If a wiki word is referenced that exists in a previous version of the software but not the current, the user can choose to start with the previous version and work from there. This way, there is a manual review step for each page.
  • The history for the “2.0″ versions of a page is a separate line than the history of the “2.1″ versions of a page. Usually, the documentation for an older version is just going to languish anyhow.

To me, this seems easy to use for a browser of the wiki, editor of the wiki and even for the creator of the wiki software. Sure, a big wiki with lots of pages will have a bit of pain for a major new release, but you’re only talking about a couple clicks per page for pages that don’t require any changes. It seems like a major release is a good time to review the docs.

A decent wiki with a feature like this would definitely make me move my docs out of Subversion. Let me know if one exists.

18 comments
September 27, 2005

Web Services Infrastructure: Kid Templating

by Kevin Dangoor

Ryan Tomayko put up an article describing the genesis of Kid as an answer for generating responses for web services. Right now, TurboGears produces HTML and JSON as part of the out-of-the-box experience. I definitely expect that we’re going to see the ability to specify a Kid template for XML output.

I think that toward the end of my time in Javaland, an increasing number of the blogs I read seemed to be doubting WS-*. The problem with a specs like WS-* is that when people just sit down to crank out a “standard API”, they’re going to try to take into account every possible need. The best APIs I’ve used, though, are the ones that focus on making the common case as easy as possible, and leaving the door open enough to deal with uncommon issues. These APIs are generally made better because people actually use them.

There’s a reason that people still use XML-RPC, despite the existence of SOAP. It’s simple and it gets the job done for a fair number of scenarios…

3 comments
September 27, 2005

Google result counts

by Kevin Dangoor

There has been plenty of speculation on the web over the years about the result counts listed from Google searches. I have my own bit of interesting Google search result trivia.

Before TurboGears’ release, searching for the word turbogears would yield a few dozen automotive-related hits, which makes sense because it wasn’t really a word or a brand name before now.

This morning, a search for turbogears yields 210,000 results. That number is so large that I find it hard to believe that even counting automatically-generated archives of things will yield anywhere near that number of pages. So, I decided to jump through the results. Google’s results took me to “981-984 of about 210,000″. Even on the *last page* of results, it was still saying 210,000. Odd, huh?

While I know that Google has always claimed that the result counts are estimates, I wonder how they compute the estimate… Even Yahoo seems inflated at 15,600.

Maybe Google’s just out to make vanity searchers happy :)

3 comments