LWN.net Weekly Edition for December 6, 2012

Google DocCamp: documentation unconference

Google played host to its second annual "Summer of Code Documentation Camp" at its Mountain View offices over the first week of December, at which teams from three free software projects gathered to sort out and write sorely-needed documentation in an intensive workshop setting. This year's participating projects were the Evergreen integrated library system (ILS), the Etoys educational programming environment for children, and the open source font creator FontForge. During the last three days of the camp each team was tasked with producing its own self-contained manual through a "book sprint," but the first two days were composed of an unconference-style workshop about tackling the challenges of documentation in an open project.

Despite the name of the event, the camp is a distinct entity from Google's university-oriented Summer of Code mentorship program (although warm in December, Mountain View is demonstrably not in the Southern hemisphere...). But the two programs do share a common theme. The facilities and amenities were donated by Google, but the week's activities were run by Adam Hyde of FLOSSManuals and Allen "Gunner" Gunn of Aspiration Tech. FLOSSManuals, of course, is a project dedicated to enabling and encouraging open source communities to write and publish quality documentation; Aspiration Tech is a training and consulting group focused on working with nonprofits and software.

Unconferring

The unconference portion of the week consisted of a series of breakout sessions exploring documentation-related subjects. The unconference format means, first and foremost, that the agenda for the sessions is not fixed in advance, but is created by the participants during the event itself. The result is a program that tackles the specific needs of the participants — which, considering the time constraints of the week, was especially important.

Gunn first led the participants in a series of brainstorming exercises in order to generate a pool of topics of interest. The participants then read through all of the suggestions and attempted to group them into recurring subjects. From the resulting ad-hoc taxonomy, Gunn and Hyde selected the initial breakout session topics. But after the first round of breakouts was over, it was up to participants themselves to facilitate the sessions, exploring the topic at hand and deciding what (if any) additional sessions needed to follow later in the day.

At first glance, it might seem like the three projects represented at the unconference would have very little in common to discuss. Yes, every open source project struggles with writing documentation, just like every open source project struggles with recruiting new talent. But the projects themselves differed considerably in scope, purpose, and technical detail. Evergreen is an integrated, server-based application suite with a web interface, used and managed by a very specific type of professional institution. Etoys is a self-contained interpreted programming environment designed for classrooms and tailored toward young children. FontForge is a graphical desktop application used for an isolated task typically undertaken only by specialists.

But the brainstorming exercises quickly revealed that the projects grapple with a nearly identical set of documentation challenges. All three struggle with accessibility and translation tasks, all three have difficulty integrating updates to documentation with updates to the codebase, all three have trouble setting up and maintaining a workflow among documentation volunteers. Consequently, in each breakout session (there were three or four simultaneously during each session slot) Gunn ensured that there was at least one representative from each of the three teams, so the teams were able to exchange information and learn from each others' experiences.

Prep work

None of the session topics lent itself toward simple "how to" answers. Rather, the goal of the breakouts was to prime each group's thinking on the documentation tasks, in preparation for the writing portion of the week that followed. But there were still insights to be found in each discussion.

For example, in the translation session (in which I participated as a representative of the FontForge team), it came out that all of the projects have found success with open source tools for translating application strings and in-program help messages: Pootle, Launchpad, and other tools handle this task quite well, providing an overview that indicates the percentage of translation completed for each available language, offering translation suggestions based on other projects' work, and so on. But none of those features are available in the systems that projects use to maintain their documentation. These string translation tools are designed to handle short snippets of text only, and typically fail on paragraph-length content: long sections of text do not fit into the boxes in the interface, and the features that track completion expect the entire text to be translated at once (which is rarely possible or desirable with lengthy discussions). Conversely, the content management systems that support multi-lingual web sites do not offer the percentage-completion tracking or suggestions that make application translation more manageable.

The other topics examined during the breakout sessions included soliciting and incorporating audience feedback, iterating and versioning documentation, developing and maintaining a healthy community of documentation writing, finding tools to support remote documentation efforts, and many more. By Tuesday, however, the program shifted away from general topics and toward the specifics that each team needed to address for its own book sprint. This meant nailing down a specific target audience and drafting an outline of what subject matter would be covered, start to finish. That can be a daunting task, particularly in light of the knowledge that only three days will be available for content creation and editing, and with teams of only five or six people.

The writing itself began in earnest late on Tuesday, and although the deadline still looms large and ominous, it is remarkable how quickly the work starts to take on a concrete shape. But that is the secret that FLOSSManuals has set out to share with the free software community: writing documentation may seem hard, but then again writing software is hard, too. And just like writing software, once the community sets its mind to the task, it can accomplish considerable feats. That lesson does not end on Friday, either; already there has been talk among the projects about what subjects ought to be tackled in future book sprints. Even though Evergreen, Etoys, and FontForge will walk away from the week with a new book, hopefully the lesson will not be limited to just those three projects, either.

[The author would like to thank Google for support to attend the 2012 Summer of Code Documentation Camp]

Comments (3 posted)

Darktable 1.1

Darktable is an open source raw photo converter with built-in image-library-management features, which puts it up against stiff competition. Previous releases boasted a wealth of functionality but were hampered by the application's peculiar user interface. The just-released 1.1 version, however, makes big strides forward in usability while still adding several interesting new features. The new features include front-end functionality, plus a command-line interface and GPU hardware acceleration through OpenCL.

We last looked at Darktable in November 2011, shortly after the release of version 0.9.3. At that time, the application offered a substantial collection of photo adjustment tools via plugins — including several tools not offered by competing raw converters like Rawstudio or RawTherapee. But the interface made them difficult to use: unlabeled controls, nonstandard widgets and status indicators, and a plugin selection palette composed entirely of cryptic, similar-looking logos.

Consequently, the biggest news for most users is that Darktable has evolved into a far more usable product, with interface updates touching most areas of functionality.

Photo editing

All of the same plugins and their icons are still available; they have simply been organized into a scrollable list, with the name of the plugin next to its logo. The downside is that it might look a wee bit less like a TIE fighter's control panel — but it is far more usable. Darktable's editing interface allows you to stack multiple adjustments on top of each other by activating their plugins. This approach is different from the model employed by other raw editors (Rawstudio, for example) in which the adjustments available are presented as intrinsic qualities of the image. In Rawstudio's approach, for instance, an image has one tone curve, and you can change it or leave it alone. In Darktable, you can adjust the "base curve," but you can also apply (for example) high-pass or low-pass filters, each of which adjusts the curve in its own particular way. Order is important in Darktable's approach; if you desaturate an image then try to adjust its color balance, you will not have much to play with.

One of the benefits of Darktable's approach is that the developers can implement quirky and original features as plugins — effects that incorporate several types of adjustment at once. In older Darktable releases, though, some of these unique effects filters exhibited the most troublesome usability hangups. The new release fixes almost all of the issues: most of the curves, axes, and units are labeled, and in most cases it is clear what effect changing a widget will have on the image. Where controls remain unclear, there is usually a pop-up tooltip with a decent explanation. Many of the controls now feature a combination label-slider-spinbox akin to the "spin scales" (or as I call them, "spladers"...) now found in GIMP.

There are new plugins and adjustment features on display as well, including conditional blending — which is precisely what it sounds like. Conditional blending allows you to apply a blend mode (e.g., "multiply" or "soft light") only to regions of the image that fall within a particular color or brightness range. There is also a nice equalizer plugin that enhances local contrast, bringing out small image details without radically affecting the overall tone of the picture.

Speaking of user interfaces, the 1.1 release also introduces a command-line interface, darktable-cli. At the moment, it is only capable of resizing images, but the potential for using Darktable in scripting is intriguing.

Photo juggling

Those of us not blessed with obsessive-compulsive tendencies tend to let our file storage get messy. In the old days, photographers would have called this the "shoebox problem" in reference to stacks of boxes filled with negatives and prints. A fully digital workflow alleviates this to some degree, but hunting for a half-remembered image in the desktop environment's file manager remains a slow and frustrating ordeal. Although an entire category of application has sprung up to offer a hand (the "image manager" like Shotwell or Digikam), most raw photo editors are still forced to incorporate some file collection management and search functionality, simply to save the user from switching back and forth repeatedly.

Darktable 1.1 adds muscle to its file management skills. By far the flashiest new feature is similar-image-search, which scours the database of imported image files looking for photos that appear "similar" visually — as scored by histogram, color, and lightness . I am particularly partial to this feature because it was one of the main selling points of imgSeek, a now-defunct project that was the subject of my first-ever published review, and remains a rarely-seen feature. As was the case with imgSeek, the results of similar-image-searching are imprecise, but if you have imported your entire collection, it would surely assist you in finding the odd mis-labeled image buried in a strange directory.

Darktable also allows you to categorize images in "film rolls" (which despite the now-archaic terminology are merely named collections), in addition to applying keywords, tags, and other metadata. How keywords differ from tags is not explained, other than the fact that they reside on opposite sides of the screen. What is more distinctive is support for geotagging images, complete with a colorful map widget. The map feature is not fully integrated into the other image management tools — instead, it is one of the four top-level application tabs (the other three being image management, photo editing, and tethering). Finally, the application has a new "Group images" mode (which is toggled on or off with a G button in the upper toolbar) which, when activated, hides redundant images, such as the JPEG versions of existing raw photos.

Darktable 1.1 thus gives you multiple ways to find the image you are thinking of, based on automatic or user-assigned metadata, image properties, and the photo's point of origin. The application also gives you quick access to common editing tasks from within the image management tab. Direct export is the most obvious task, but Darktable can also take a select set of differently-exposed images and blend them into a high dynamic range (HDR) image, or it can immediately apply a user-defined "style" with one click of a button. These styles amount to templates; to define one you select an image to which you have made changes and save its current state as a new style.

Shoot first, accelerate later

The last of the new user-visible features in the new release is support for live previews in tethered shooting mode. Tethered shooting refers to capturing images from a camera connected to the computer over USB. There are several practical reasons for tethering, including the ability to see larger and higher-quality output than can be displayed on a camera's LCD screen. But tethered shooting can also be helpful when setting up complicated studio shots, such as time-lapses, macro-photography, or tricky-to-capture phenomena (imagine capturing the arrow-striking-an-apple shot, for instance). Live preview makes setting up and double-checking these carefully-managed shoots far simpler.

Darktable 1.1 has new features under the hood, too. The most prominent is support for GPU-based hardware acceleration, which arrives courtesy of OpenCL. OpenCL support benefits users by speeding up image transformations. When working with high-megapixel raw images, every speed increase is important, because users want to see even minute changes in settings reflected as soon as possible on the screen. The trend in camera-making is to add more megapixels with every release, of course, and these days the low end of the price spectrum offers more pixels than the high end did a few years ago — so time-saving is not the concern of professional photographers alone. Darktable, like GIMP, uses the GEGL library to perform image transformations. As we mentioned in May 2012, GEGL has been slowly but surely adding OpenCL support to its operations in recent years, most recently through the work of developer Victor Oliveira. OpenCL "kernels" are functions which can be executed in parallel on GPUs or CPUs, and they are architecture-independent (unlike, for example, NVIDIA's CUDA). Thus, systems with a supported GPU automatically get GPU acceleration, but all multi-core CPU systems automatically get multi-threading, too. At the moment, the proprietary graphics drivers from NVIDIA and ATI offer the best support for OpenCL, although the Nouveau driver project is making progress on its own.

The list of changes since the Darktable 0.9 series includes other features, too, but the most significant for the average user will no doubt be the improved user interface. There are still quirks, but the team has done an excellent job of fixing the biggest usability blockers — and doing so without sacrificing the design aesthetic that earlier releases established. Darktable's approach to image editing has always been different from the other open source raw converters. When its own user interface does not get in the way, it makes a much stronger case — and, more importantly, it lets the user experiment with the unique features, and stumble across interesting effects.

Comments (9 posted)

2012 Linux and free software timeline - Q2

Here is LWN's fifteenth annual timeline of significant events in the Linux and free software world. We will be breaking the timeline up into quarters, and this is our report on April-June 2012. Timelines for the remaining quarters of the year will appear in the coming weeks.

• January-March 2012

This is version 0.8 of the 2012 timeline. There are almost certainly some errors or omissions; if you find any, please send them to timeline@lwn.net.

LWN subscribers have paid for the development of this timeline, along with previous timelines and the weekly editions. If you like what you see here, or elsewhere on the site, please consider subscribing to LWN.

If you'd like to look further back in time, our timeline index page has links to the previous timelines and some other retrospective articles going all the way back to 1998.

The 2012 Linux Storage, Filesystem, and Memory Management Summit is held in San Francisco, April 1-2 (LWN coverage: day 1 and day 2).

Debian joins the Open Source Initiative as an affiliate (announcement).

The udev maintainer announces that the udev and systemd projects will merge, noting that it will still be possible to run udev on a system that is not using systemd (announcement).

Yukihiro "Matz" Matsumoto, creator of the Ruby language, wins the 2011 Free Software Foundation award for the advancement of free software (announcement).

Red Hat celebrates becoming the first open source company to turn over one billion dollars in a fiscal year with a US$100,000 donation to open source projects (LWN blurb).

The Kubuntu project acquires a new sponsor, as Blue Systems hires two former Kubuntu developers away from Canonical (LWN blurb and article).

The 2012 Linux Foundation Collaboration Summit take place in San Francisco, April 3-5 (LWN coverage: Trademarks for free software projects; The kernel panel; X and Wayland; The Linux System Definition; The future of GLIBC; LLVM and Linux).

Maintenance of the Linux 2.4 kernel comes to an end, eight years after the release of Linux 2.6.0 (announcement).

PostGIS 2.0.0 is released (announcement).

The Samba team announce a fix for a remote code execution vulnerability (LWN blurb).

The 2012 Linux Audio Conference takes place in Palo Alto, California, April 12-15 (LWN coverage).

Stefano Zacchiroli is re-elected for a third term as leader of the Debian Project (announcement).

MythTV 0.25 is released (LWN article).

FreeBSD 8.3 is released (announcement, release notes).

Calligra 2.4 is released (LWN blurb and article).

Nathan Willis joins LWN as an editor (LWN article).

gitolite v3.0 is released (announcement).

OpenSSH 6.0 released (announcement).

Geary 0.1 is released (LWN article on this GNOME-based email client).

The Defensive Patent License is released (LWN article).

OpenBSD 5.1 is released (announcement).

The Tizen project announces the 1.0 ("Larkspur") release of its SDK and platform source code (LWN blurb and article).

Ubuntu 12.04 LTS "Precise Pangolin" released (announcement).

Yocto Project 1.2 is released (announcement).

Xfce 4.10 is released (LWN blurb).

The Libre Graphics Meeting 2012 is held in Austria, Vienna, May 2-5 (LWN coverage: Inkscape quietly evolves into a development platform; GIMP's new release, new über-core, and future; Unusual typography).

The inaugural Tizen conference takes place in San Francisco, 7-9 May (LWN coverage: Pitching HTML5 as a development framework).

Dell announces Project Sputnik, which is aimed at creating a commercial, Linux-based developer laptop (LWN blurb).

Apache OpenOffice 3.4 is released (LWN blurb, pointer to an earlier timeline of the work on the project, and an earlier article looking at progress of the project).

The GNU nPth project makes a first release of its GNU portable threads library (announcement).

Open Build Service version 2.3 released (announcement).

GIMP 2.8 is released (release notes, LWN blurb and article previewing the release).

The Document Foundation announces a certification program "to foster the provision of professional services around LibreOffice" (announcement).

Red Hat Enterprise Linux turns 10 (press release).

ConnMan 1.0 is released (LWN blurb).

Kdenlive 0.9 is released (announcement).

PowerTOP v2.0 is released (LWN blurb).

PulseAudio 2.0 is released (announcement).

PGCon 2012 is held in Ottawa, Canada, May 17-18 (LWN coverage).

Mandriva SA announces it will return control of the distribution back "to the community". However, the Mageia community distribution that earlier forked from Mandriva declines to work with Mandriva's community effort (announcement, LWN article on the announcement and an earlier article on the status of Mandriva).

The printerd project is announced (LWN article).

Linux 3.4 is released (announcement; KernelNewbies summary; LWN merge window summaries part 1, part 2, and part 3; LWN development statistics article).

Mageia 2 is released (announcement and LWN article).

LLVM 3.1 is released (announcement, release notes)

Nmap version 6 is released (announcement).

ownCloud 4 is released (LWN blurb).

Perl 5.16.0 is released (announcement and LWN article).

The jury in Oracle v. Google finds that Google did not infringe any of Oracle's patents (LWN blurb and earlier article on the case, Groklaw follow-up).

Simon Phipps becomes president of the Open Source Initiative (The H article).

The LibreOffice project embarks on a project to rebase and relicense the LibreOffice source code (LWN article).

The Software Freedom Conservancy announces that it is expanding its license compliance efforts after signing up multiple Linux kernel and Samba developers whose copyrights can be used in license compliance efforts (article).

Fedora 17 is released (announcement).

GCC explorer is released (LWN blurb).

RPM 4.10 released (LWN blurb).

systemd 183 is released; this release merges the udev and systemd projects (announcement).

The Linux Foundation announces the existence of the FOSS Bar Code Tracker, a tool for tracking free and open source software components (announcement).

In the Oracle v. Google suit, Judge Alsup rules that the Java APIs are not copyrightable (LWN blurb).

Obnam 1.0 is released (LWN blurb and article on this backup system).

LinuxCon Japan is held in Yokohama, June 6-8 (videos; LWN coverage: Making kernel developers less grumpy; OpenRelief launches; One zImage to rule them all; Advice for new kernel hackers; The business of contribution).

Debian accepts a diversity statement (announcement).

Linus Torvalds co-wins the Millennium Technology Prize (BBC report).

The Apple versus Google-owned Motorola patent litigation takes a surprising turn as Judge Richard Posner dismisses the case, calling the patent system "dysfunctional" (GigaOm article).

Emacs 24.1 is released (announcement).

MPlayer 1.1 is released (LWN blurb).

X11R7.7 is released (announcement and LWN article).

SystemTap 1.8 is released (announcement).

Ulogd 2.0.0 is released (announcement).

The Electronic Frontier Foundation announces the Defend Innovation patent reform project (press release).

The Fedora and Ubuntu distributions outline their plans for dealing with UEFI secure boot (LWN article on the Fedora plan and the Ubuntu plan).

Red Hat Enterprise Linux 6.3 is released (LWN blurb, release notes).

Grub 2.0.0 is released (announcement).

The GNU C library (glibc) version 2.16 is released (announcement).

Many Linux servers misbehave as a result of the leap second added at the end of the month (LWN article).

Comments (1 posted)

Page editor: Jonathan Corbet

Inside this week's LWN.net Weekly Edition

• Security: Picking a MAC address for a FreedomBox; New vulnerabilities in Claws-mail, Firefox, Kernel, Perl, ...
• Kernel: Syslog namespaces; Optimizing stable pages; PowerClamp.
• Distributions: CyanogenMod 10 on the Nexus 7; NetBSD 5.2, EOL announcements, ...
• Development: The synthesizers of Sean Bolton; Guile, Ekiga, shim, Buildroot, ...
• Announcements: MariaDB Foundation, 2012 LinuxCon Europe videos, newsletters, events.