Weekly Edition
Return to the Development pageRecent Features
| |||||||||||||
The Free Software Directory's Documentation Vacuum
One of the numerous duties your development page editor must do each
week is to scan a list of web sites for announcements of
new and updated open-source software packages. Several criterion are
used to select software announcements for inclusion in the weekly edition.
The most important points include usefulness of the software to a
wide range of people, the existence of documentation describing
the project, and availability of documentation describing the changes
in the just-released version.
Over the years, many projects have been added to this list, and many others have been removed, due to either project stagnation, or ineffective project documentation. The list itself is a bit too ragged for publication here. One site that gets visited one or more times each week is the FSF/UNESCO Free Software Directory. It contains a list of the most recently changed open-source applications, as well as categorized listings of over 3,000 packages. It's a great place to find just about any kind of software you may need, and get a real feel for the wealth of open-source applications that are available. Unfortunately, a common problem has been observed with the majority of the new releases listed on the site: discovering what the changes are in the latest versions. We'll look at the latest release of etherboot as an example. We're not picking on this particular project in any way, it's just one of many cases. Starting with the FSF/UNESCO Free Software Directory, we see an interesting package listed in the Ten most recently updated entries section:
etherboot - [The GNU General Public License, Version 2] - 2004-06-28 Makes boot ROMS
Cool, there's a new version this week. Clicking on the link to the etherboot announcement, we see, among other things,
Version 5.3.8 (devel) released on 2004-06-28.
So far, so good. But here's where things begin to get dicey. The announcement page links to the source code (stable version only), various mailing lists, documentation, and the project web page. But we want to get development version that we saw in the previous announcement. Moving to the project web page, we get a typical project presentation with the usual links. Let's see if there's anything about the new release under News. Nope, just a link to the project's SourceForge page. Finally, we're getting somewhere. Using the age-old axiom, Use the Source, Luke, we download version 5.3.8. Interestingly, the download date for this release has mysteriously changed to June 12, 2004. Downloading takes us through the usual series of intermediate steps to select a local server, before beginning the operation. Now, we have a local copy of the source file. An invocation of tar yields the source tree. Change into the source tree, and FINALLY, there are some release notes:
As of Etherboot 5.3.8:
There is no longer a default target for make. You must specify an
argument to make. Help text is now provided to indicate possible make
targets.
binutils-2.14 is no longer needed in order to compile images. The
symbolsrec feature is not used, so older binutils (ld) should work.
That took an awful lot of clicking through web sites across the net, the need for a lot of disk space, some bandwidth, the knowledge of dealing with bunzip2 and tar, and a fair amount of patience. There really ought to be a simpler way to get this kind of information out. Often, your griping (but not necessarily grumpy) editor simply moves on to the next project in search of more accessible documentation, and the cool new software doesn't get the attention that it deserves. Finally, a frequent problem with software announcements is the lack of any kind of date associated with a new version announcement. Free software writers would be well advised to add a few trivial bits of information to their releases, and make sure the information is easy to find. Doing so would probably do wonders for expanding the user base. (Log in to post comments)
The Free Software Directory's Documentation Vacuum Posted Jul 1, 2004 0:54 UTC (Thu) by tzafrir (subscriber, #11501) [Link] Actually, part of the process of adding a new release to SorceForge is adding release notes and a change-log.The link to the release notes on the download page is a bit non-intuitive (the link to the "name+version" of the release) . Yet the release notes for that version are certainly informative: http://sourceforge.net/project/shownotes.php?release_id=245527
OpenLDAP CHANGES Posted Jul 1, 2004 3:01 UTC (Thu) by nicku (subscriber, #777) [Link] When I want to find out what has happened to the latest release of the wonderful OpenLDAP, I have not found an easier alternative to downloading the large source code tarball, then reading the CHANGES file. Now you point it out, yes, it would be so great if that information were easily accessible from the web site.Okay, after finishing my current work commitments, I will raise it on the mailing list.
OpenLDAP CHANGES Posted Jul 1, 2004 19:40 UTC (Thu) by obobo (guest, #684) [Link] I haven't used OpenLDAP myself, but this looks like a changelog:http://www.openldap.org/software/release/changes.html from I'd say (given that the Etherboot changelog was on SourceForge, as tzafrir pointed out), that the problem isn't that the documentation is unavailable, it is that people don't know where to look for it (so we need more and better pointers to it in the release announcements).
Another possible strategy Posted Jul 1, 2004 9:06 UTC (Thu) by xyz (subscriber, #504) [Link] Usually when I am searching what has changed in a project I search for available cvs viewer. So in this case of sf.net I go to the view cvs and search for Changes, or similar. This is just a shortcut, and the main problem remains, but still easier to access. Just my 2 ยข (Euro cents.)
The Free Software Directory's Documentation Vacuum Posted Jul 8, 2004 7:49 UTC (Thu) by wildpossum (guest, #17744) [Link] Jon, thanks for that review. No we are not offended in any way and it's a useful poke for us to fix our web pages. Part of the problem is that the layout dates from before Sourceforge, and we should put some effort into reusing some of Sourceforge's existing pages. The other is that our development group tends to be all software developers and we'd dearly love for some web designer to volunteer give our site a sexy makeover. In the meantime I'll take the suggestions and reduce the links that the reader has to chase and get our release managers to post more useful information in the release notes.
|
|||||||||||||