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.
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
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.
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
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 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
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.
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
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,
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
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.
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
Comments (9 posted)
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.
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 email@example.com.
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).
I think one of the things that makes Debian off-putting
and unwelcoming is that we're a little *too* obsessed with criticizing
everyone's ideas, and what some people see as "healthy discussion" other
people see as "hurtful flamewars over bike shed colors."
-- Russ Allbery
Yukihiro "Matz" Matsumoto, creator of the Ruby language, wins the
2011 Free Software Foundation award for the advancement of free
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).
We don't need a system to help us ignore bug reports; our
existing process handles that with admirable efficiency.
-- Robert Haas
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
A couple of times I've said "It looks like you could use
some help. Would you like me to co-maintain with you?" and have generally
gotten a positive response. If it's put in terms of "Looks like you're
busy, I can help" and not "You suck and should be fired so I can take over"
people seem to be pretty open to it.
-- Scott Kitterman
MythTV 0.25 is released (LWN article).
FreeBSD 8.3 is released (announcement, release
Calligra 2.4 is released (LWN blurb
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).
An Apple programmer, apparently by accident, left a debug
flag in the most recent version of the Mac OS X operating system. In
specific configurations, applying OS X Lion update 10.7.3 turns on a
system-wide debug log file that contains the login passwords of every user
who has logged in since the update was applied. The passwords are stored in
The Tizen project announces the 1.0 ("Larkspur") release of its SDK
and platform source code (LWN blurb and
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
The inaugural Tizen conference takes place in San Francisco, 7-9
May (LWN coverage: Pitching HTML5 as a
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
The GNU nPth project makes a first release of its GNU portable threads
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
Enough data has come in to satisfy me that with all the
improvements in Linux over the last year, and with BQL, codel and fq_codel,
that we've won a major battle in the war against bufferbloat
-- Dave Täht
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).
When I helped to develop the open standards that
computers use to communicate with one another across the Net, I hoped for
but could not predict how it would blossom and how much human ingenuity it
would unleash. What secret sauce powered its success? The Net prospered
precisely because governments — for the most part — allowed the Internet to
grow organically, with civil society, academia, private sector and
voluntary standards bodies collaborating on development, operation and
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
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
Simon Phipps becomes president of the Open Source Initiative (The
The LibreOffice project embarks on a project to rebase and relicense
the LibreOffice source code (LWN article).
I couldn't have told you the first thing about Java
before this problem. I have done, and still do, a significant amount of
programming in other languages. I've written blocks of code like rangeCheck
a hundred times before. I could do it, you could do it. The idea that
someone would copy that when they could do it themselves just as fast, it
was an accident. There's no way you could say that was speeding them along
to the marketplace. You're one of the best lawyers in America, how could
you even make that kind of argument?
Alsup (Oracle v. Google) has a clue
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
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
In the Oracle v. Google suit, Judge Alsup rules that the Java
APIs are not copyrightable (LWN blurb).
Managing a volunteer open source project is a lot like
herding kittens, except the kittens randomly appear and disappear because
they have day jobs.
-- Matt Mackall
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
From the tone of the hearing, and the language of the
House resolution, we are being asked to believe that "the position of the
United States Government has been and is to advocate for the flow of
information free from government control."
If only it were true. The reality is that Congress increasingly has its
paws all over the Internet. Lawmakers and regulators are busier than ever
trying to expand the horizons of cyber-control across the board: copyright
mandates, cybersecurity rules, privacy regulations, speech controls, and
Brito and Adam Thierer
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
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
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
Grub 2.0.0 is released (announcement).
Documentation is the sort of thing that will never be
great unless someone from outside contributes it (since the developers can
never remember which parts are hard to understand).
-- Avery Pennarun
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
Next page: Security>>