Ying Tong Iddle I Po

Recently I’ve been looking around at the Linux Developer Network. For those who aren’t aware of the project it is, partly, an attempt to create a resource similar to the Microsoft Developer Network. It is in no way even slightly comparable given the way I use MSDN.

I’m going to assume I’m a fairly typical programmer and, when coding for Win32, use MSDN in a typical way. That way is usually to type “<functionality I require> msdn” into Google and make use of the vast swathes of API documentation and API HOWTOs available there. In my selfish view a really useful resource would have the following properties.

• Be a single point of contact for links to, or mirrors of, the best documentation for FOSS libraries and applications.
• Crucially, be useful for the working programmer/sysadmin. We’re not pushing politics here, we just want to drill down to docs that are available. Ideally there should be a menu down the left hand side which lets you get at the goods quickly.
• Have bucket loads of API documentation all available in an AJAX-y goodness tree list and no more than two or three clicks from the front page. This surely can’t be too difficult in that many existing projects have good-quality, machine-readable, documentation available under a free license.
• Related to this it should be accessable with a plain ol’ HTML tree list for lesser browsers and, most importantly, so it can be crawled by search bots! It should be bookmarkable and one should be able to middle-click hyperlinks to queue up a load of tabs for easy switching. Basically all the things wrong with AJAX-y goodness should be fixed.
• Be categorised by subject, project and documentation type. This means that under a hypothetical ‘Networking/Samba’ node there would be nodes like ‘Books’, ‘Reference’, ‘Tutorials’, etc which are either mirrors of or links to documentation cherry picked.
• Make said selection and cherry picking all Web 2.0 friendly. By this I mean have some sort of emergent system whereby all users can submit and categorise documentation, rate it and have the cream rise to the top. Obviously there are lots of subtleties to do with this but the principle appears to work for things like Digg. Oh, and it should have gradients and rounded borders.
• Have a fairly unique abbreviation to make a Google search work the way I want. “LDN” is not terribly unique. Naming a project is really hard but generally it should be easier to find a relatively under used four letter acronym. We might have ‘Comprehensive Linux Developer Network’ or CLDN for example.
• For machine-readable docs, try to impose a standard, configurable, style on top. For example, documentation can be linked to, submitted, fetched, etc and parsed be it in Doxygen, JavaDoc, Monodoc and Qt/GTK style. It should then just look as if it is part of the site.
• Be fast. I want to click on a link and get the damn page. I don’t want to see my browser spaz as it hits a redirect loop in an attempt to escape from or add a huge wrapping of frames. I want it to be as responsive as GMail as a minimal standard.

So how can this happen? Well the above bit of rant could start as a high-level design goal for a really useful developer website. A website that, when I want to remember the order of arguments for FrobnicateFoo(), I can just Google for “FrobnicateFoo CLDN” and be plopped into a familiar documentation system and easily navigate to more in depth articles on the library. Currently the top hit for “FrobnicateFoo libname” is rarely the API docs.

Who will create this website? Ideally someone with experience with such things backed by a big distro. In reality it’ll probably have to be muggins here. The problem is I have very little experience with trying to set up ‘proper’ websites. Mono’s documentation site seems to be a good starting point (except that it suffers from some AJAX-y goodness bugs).