Frustration, thy name is trying to work on two projects

Last Tuesday I gave a talk at the Cape LUG about what I saw for the future of GNOME-Ubuntu relations. I didn't paint a pretty picture. A full half of my talk consisted of me moaning about how crappy it is that minor differences between the two projects are repeatedly being blown out of all proportion, resulting in the current river of bad blood we find ourselves wading through. (The other half was filled with my customary suite of bad jokes and incoherent rambling.) Interestingly, Mark Shuttleworth was also in town and dropped by [1] to listen and respond to some of my points. This was certainly welcome because it helped me to understand some of the decisions Canonical has made recently. Besides, it was a nice gesture.

Perhaps some context for what follows is in order. I'm an Ubuntu person who spends most of his time working upstream in GNOME. I do this because I think my work can benefit the wider community as well as Ubuntu users (and, erm, because I enjoy working on GNOME). It can be a bit crappy sometimes, though.

For starters, some [2] people in the GNOME community moan about how Ubuntu doesn't pull its weight upstream. They then make it difficult for Ubuntu-y folks to contribute things upstream. People within the Ubuntu community, Canonical employees included, have tried to make significant contributions and have been knocked back on several occasions [3], in most cases not for any particularly good reason I would judge. I've even heard stories about Canonical having to upstream patches via a third party because a GNOME maintainer wouldn't accept (identical) patches from them! (I know; citation needed.) There is an anti-Ubuntu (or at least anti-Canonical [4]) sentiment in parts of the GNOME community.

Equally, there is a frustration with GNOME in some quarters of the Ubuntu community. Rather than joining in on the GNOME side of things and developing upstream, people see the processes and dynamics of GNOME as hurdles to doing what they want to do. It seems easier to go off and partially reinvent the wheel than to try working with people who don't share your exact vision of the free desktop [5]. Of course, there is no middle ground to be had, and the "irreconcilable differences" which prevent us from working together on one thing or another often lead to "completely different" approaches being taken, like Unity and GNOME Shell [6]. This way of doing things is often a gigantic waste of time and reinforces the opinion of some in GNOME that Ubuntu isn't a team player.

To round-off this sketchy analysis of a complicated situation, I should also mention Canonical's role in all of this. Canonical are a for-profit company and intend to make money from the Free desktop. On paper at least, I think most people in the GNOME (and Ubuntu) community are happy for people to make money from Free software. The method you use to make that money is subject to intense scrutiny, however. Free software companies are already at a disadvantage compared to proprietary software businesses when it comes to making money [7], and insisting that all of their attempts to generate revenue fit into some warm, fuzzy picture of a benevolent cooperative for whom profit is incidental is unreasonable [8]. Sorry folks, but it's the 21st century - even charities are getting cutthroat when it comes to fundraising, because they realise you can do more good by playing the capitalism game whilst remembering to stop short of the excesses of Big Business.

If you want the Free desktop to be successful, to gain significant market share, to compete with some of the biggest, most ruthless companies in existence, you're going to have to throw away some of your ideas about how this should work in an ideal world and start playing hard ball. I think this is what Canonical are trying to do. And yes, that involves exploiting [9] the community to some extent, and of course people are upset about that. I don't think Canonical are hell-bent on milking FOSS for all it's worth, but they do require some freedom to operate. Having said that, if Canonical want to push the view that a pragmatic, corporate approach to Open Source is the route to success, then they're going to have to do a lot better at not making people feel used. Things like splitting Banshee's Amazon referrals and insisting on copyright assignment cause bad feeling without bringing in much dough, I would imagine.

My point is that the bulk of this bickering is counter-productive and unnecessary. Open source desktops are hardly swimming in market share, and I doubt chronic infighting will remedy that situation. I don't care who started it, or who is in the wrong. From my point of view, the whole situation is depressing and demoralising. If it continues, chances are I won't want to work in either community. But the differences are reconcilable! GNOME can understand and facilitate Canonical's commercial goals and can be more accepting of Ubuntu people and their way of doing things; Canonical can benefit from the fruits of the Ubuntu and GNOME communities' labour in a more sensitive way; and Ubuntu contributors can resolve to work upstream more. All it will require is for some people to swallow their pride and/or make small compromises [10].

1 In a Darth Vader mask. Really. There are photos somewhere.
2 I would like to draw your attention to my careful use of the word "some" throughout this post.
3 I'm thinking of things like Zeitgeist, app indicators (which are a Free Desktop standard!) and so on.
4 I fully understand that Ubuntu and Canonical aren't the same thing, and that there are tensions between them. They often get tarred with the same brush upstream, though.
5 The decision to switch to Unity instead of GNOME Shell is symptomatic of this. I asked Mark about that decision and he said that attempts were made to get Canonical design people working with GNOME design people etc. etc. and no agreement could be reached. Despite this fundamental disagreement between the two camps, Unity and GNOME Shell are doing a great job of looking and feeling almost identical to one another.
6 Sorry to harp on about it, but GNOME Shell and Unity are extremely similar, to the point where hardly any of the differences offer tangible benefits to the end user. Helpfully, they're just different enough to cause massive problems for documentation and support people though. Working together on one new shell would have been possible on purely technical grounds.
7 By this, I mean that factors like the code being open mean that it can be more difficult to get users to pay up; revenue streams other than the obvious, directly selling the software, must be found. Of course, Free software has plenty of advantages in terms of reduced development costs, community contribution and the like.
8 To pick an example at random:
"I thought you understood the spirit of Free Software, but you're just another normal company that is first going after money."
9 An ugly word, but I think it's the right one. You're making money by taking other peoples' work and packaging it up, without offering them any reward for that work (monetary reward, at least).
10 I will be swallowing some of my pride by working on documentation for Unity and assigning the copyright to Canonical.

Cape Town; Talks

It turns out that I've been in Cape Town for the last three weeks, hiding from my documentation responsibilities in the rather picturesque Department of Maths and Applied Maths at UCT. (They use Ubuntu here!) Shaun is dragging me across the Atlantic in mid-March to make up for it though. Rumours that I was bribed with biscuits are almost certainly unfounded.

Anyway, while I'm here I'll be opening my mouth on numerous occasions:
  • On Monday the 21st of February I'll be giving a talk on "Contributing to open-source documentation" at AIMS in Muizenberg.
  • On Tuesday the 22nd I'll be talking about "Future conflicts between the Ubuntu and GNOME communities". Catchy title, huh? It's at the LUG meeting on UCT Upper Campus. See the CLUG wiki for more information.
  • On Tuesday the 1st of March I'll be giving an academic talk on "Testing homogeneity on large scales with the kinematic Sunyaev-Zel'dovich effect". That's at 12 noon in the Maths building at UCT.

App maintainers: It's time to embrace the duck

Documentation superstar Tiffany Antopolski sez:

The Gnome Documentation Team is working on updating help to Mallard docs. We have a list of applications that still need their user docs converted to Mallard. That list can be found here.

I would like to ask maintainers to have a look at the wiki. If you have info for the wiki, please add it. Or, if you know someone interested in working on your help, please introduce us to them (and maybe add their name to the wiki).

If you have any questions, please feel free to get in touch with the Gnome Documentation Team.

We're looking for some more writers to help with the conversion process - get in touch!

Guest Post: Laura MacPhee on the Canonical Contributor Agreement

I've been finding it difficult to balance my work on the GNOME and Ubuntu documentation recently. Apart from the usual lack of time, the increasingly divergent directions of the two projects have seemed difficult to reconcile in the help we provide. Ubuntu has always customised GNOME, but with the recent announcement that Ubuntu 11.04 will default to Unity rather than the new GNOME shell, I think we may have lost a great deal of the practical documentation compatibility between the two. This is a shame, because the differences between shells are really only superficial. Unfortunately, details matter in user help.

It's another "divergence" altogether that looks set to cause the most serious problems, though. A bug report was recently raised requesting documentation for Unity. So far, so good - it's a perfectly sensible subject for the Ubuntu docs team to handle. However, it seems that the docs can only be accepted into Unity itself if we sign the Canonical Contributor Agreement, which assigns copyright to Canonical. We could provide documentation for Unity and keep it in the ubuntu-docs package (or a standalone unity-docs package), which isn't subject to the agreement, but that would make it more difficult for the Unity docs to be used upstream. There's also the risk that Canonical will want to distribute docs under an incompatible license and so would simply rewrite them, invalidating all of our work.

Personally, I don't want to sign Canonical's agreement. I want to share my writing, not give it away. Other team members seem to feel the same. So where does this leave the Ubuntu docs team?

I've invited my good friend (and favourite legal expert) Laura MacPhee (Twitter, LinkedIn) to write about the issue. Laura has a BA in Jurisprudence from the University of Oxford, is a contributing author of Scots Law for Journalists (8th Ed.), and currently writes for the Open Rights Group. Note that she's writing here in a personal capacity.

Laura MacPhee on the Canonical Contributor Agreement

Ideological conflict has carved the pathway of human experience. Imagine how different history would be without it. There would have been no crusades. Northern Ireland would have been relatively untroubled. The Mitfords would have been an unremarkable aristocratic family. In reality individual philosophy is a very powerful force, which now looks set to define the future prosperity of Canonical.

I am, of course, referring to the controversial agreement which Canonical requires its contributors to undertake. The crux of the issue can be seen in the first term:

I hereby assign to Canonical with full title guarantee all copyright now or in the future subsisting in any part of the world in any Assigned Contributions.

In assigning the copyright in one’s work under an agreement like this one, the contributor essentially loses his ownership in the work. The issue of ownership is a deeply emotive one which is connected to our sense of self-worth and achievement. Most contributors can surely relate to the Lockean theory of property, whereby a creator is entitled to “the work of his hands”.

The broad scope of the licence granted by Canonical means that this is a philosophical problem rather than a prima facie practical barrier. This is not an uncommon business model, and makes commercial sense for the company. However, this benefit must be weighed against the cost. In this case Canonical risks undermining its own vision of a community-oriented project as well as contravening the open source philosophy as a whole. This dimension of Canonical’s philosophy is very attractive to contributors and should not be dismissed so casually.

This form of this agreement creates a clear divide between the contributors who produce the code and the company which owns the rights to it. This reflects more traditional ideas of corporate hierarchy; and conflicts with the community-oriented ideals Canonical purports to espouse. This has provoked a wave of unrest amongst contributors. They are disappointed by the wording of the agreement.

The sixth term presents a particularly contentious point:

Canonical will ordinarily make the Assigned Contributions available to the public under a "Free Software Licence"... Canonical may also, in its discretion, make the Assigned Contributions available to the public under other license terms.
There is no guarantee that these “other licence terms” will not be proprietary terms. Indeed Canonical seems to foresee this as a possibility. This prospect is understandably abhorrent to most open source contributors. They may choose not to contribute to a project which operates in this way, producing a de facto chilling effect.

Naturally, this would be very detrimental to Canonical, who should prioritise a review of their contributor agreement. Open source is more than a methodology, it is an ideology. Its aficionados are unlikely to submit to such an affront to their beliefs, and nor should they.

Fall of the Berlin Wall, November 1989. An Eastern guard speaks to a Westerner through a broken seam in the wall. Both were smiling, representing the jubilant spirit of the day. Sharon Emerson, released under a CC-BY-SA license.
Image: Sharon Emerson. Released under a CC-BY-SA license.

Structuring developer tutorials; Realising the educational promise of open source code

Structuring developer tutorials

Chris Kühl
makes some good points about choosing style and structure in the developer docs that we've been working on recently. He answers his own questions in his post, but I thought I'd elaborate on them:

How do we structure the tutorial? Daniel’s Magic Mirror example incrementally builds up the program while others, including mine, explain the finished program.
Incrementally building-up the example is the best idea, I think. This allows you to present the material in a logical order, building-up concepts as you go. The structure of the code doesn't necessarily mirror the order of the steps you would take to write it, for instance. You should have the full, finished code in a linked-off file anyway, so the reader hopefully won't get completely lost when you start changing around blocks of code. Keeping related concepts together and then building them up allows the reader to concentrate on understanding one thing as a coherent set of ideas before moving onto the next set of concepts. Try to match the tutorial's structure to the way the reader will need to think about the code rather than how the code is laid-out in the source file.

How does one reference the code? Do we use line numbers, show full functions/classes? Do we include unexplained code in the code snippets?
Line numbers are a bad idea because they're difficult to maintain (code changes!) and they force you to refer back to the code listing. If you include the actual line (or part of the line) of code that you're referring to inline, the reader can see it right there and doesn't need to waste time trying to find it again in the code listing to remind themselves what it's for. Normally, simply referring to the function being called is sufficient for the reader to be able to understand what you're talking about.

A small amount of unexplained code is fine, as long as it's obvious what it does. If you have several lines that don't need explaining, break up the snippet into two bits that surround that unexplained block. That way, you're focusing on the important material and not distracting the reader.

How do you show a full listing? Do we append a full code listing at the bottom of the tutorial or provide links to files?
I recommend linking to a file - that way, you can just copy and paste the whole file and compile it, without having to muck around with a text editor. It also makes the guide shorter and less daunting. Plus, it's easier to maintain separate code files because you can test/compile them directly.

How much should we comment the code? If the code is going to be explained, do we need to repeat the same thing in the code comments?
Don't comment the code in the code listings inside the tutorial. It's distracting: the point of the tutorial is that you're explaining the bits of code that need explanatory comments! If it's expedient, short comments can be used to skim over unimportant points if you really need to (e.g. "This exits the app"), but anything more gets in the way of the code. Of course, the separate source code file you provide should be well-commented, but not to the extent that the comments make it difficult to follow the code.

Realising the educational promise of open source code

Chris also brings up undocumented code examples. He thinks that "we should promote getting as many code examples in as many core languages" as possible. This is really sensible - inspecting an example which is known to work is a good (and well-used) way of getting to grips with a technology, and writing example code takes much less effort than writing a tutorial. It's nowhere near as good as a tutorial for people lacking a conceptual understanding of what you're doing, but a moderate sprinkling of comments and relative simplicity of the example is normally enough to get people some working code.

But, being an open source project, we can offer something of a similar value without even having to go to the effort of writing new examples. All of our code is open and free to view in git, so why not link to examples in existing projects? This has the advantage of showing the code working "in the real world", displaying it in context, with all of its supporting infrastructure. Sure, links can get broken, and real-world examples aren't as clean as purpose-made ones, but I do think it's something we should pursue. Maybe a "Real-World Examples" section on would do the trick? Would this be useful to you?

GNOME Developer Demos; Terminology; HIG 3.0 in Mallard; Cheesy sounds?

I've had a great time at the GNOME DevDocTools hackfest in Berlin this past week. Thanks to Openismus for hosting us, the GNOME Foundation for sponsoring my travel, Kat and Dave for putting me up, and everyone who attended for contributing to a really great atmosphere! There's going to be lots of fallout from the hackfest, which is the mark of a successful meet-up. Details follow; see Johannes' post for more.

Developer Demos

As part of our aim to improve the experience for new/prospective GNOME developers, we decided to produce a set of high-quality introductory tutorials. The brief was to have the reader write a small but interesting program which demonstrates several key GNOME technologies, and to have them do it in a short time (perhaps over lunch?) if possible. Each tutorial would be written in five of GNOME's key languages (C, C++, JavaScript, Python and Vala), and each tutorial would be enough to launch a newbie into programming with GNOME 3.0.

Here's how the set of tutorials looks so far (X denotes either completed code or a completed guide):

NameC (code)C (doc)C++ (code)C++ (doc)JS (code)JS (doc)Py (code)Py (doc)Vala (code)Vala (doc)
Audio Player        X 
Guitar TunerXX        
Image ViewerX~  XX    
Magic Mirror        XX
Message Board~X        
Photo WallXX        
Record Collection    XX    

The C version of the Guitar Tuner has been fully edited, so that's probably the best-looking guide right now. The JavaScript Image Viewer is hot on its tail, and most of the others are close behind in at least one language. It's looking good, thanks to all the great work by the guys who attended the hackfest. We're not doing too well on C++ and Python though; no-one at the hackfest attempted a C++ version, and there were problems with the Python GObject Introspection stuff.

This is all in git right now; you can check it out with git clone git:// (the files are in demos/C). If you're interested in helping out, please get in touch with the GNOME Doc Team! Converting the existing demos to a different language isn't hard, and some of the material in the guides can be shared between languages. We'd love to have as many of these completed as possible before 3.0; they're going to look awesome as the centrepiece of the shiny new More tutorials are planned (a D-Bus client, for example), and we could really use a hand with a simple Telepathy example too. Are you up to the task?

(For the git-impaired: Nightly builds here.)


Shaun and I worked on fleshing-out some new terminology guidelines - it works so much better in person than through IRC or a mailing list. These will be folded into the HIG and what may or may not materialise as a new documentation style guide.

HIG 3.0 in Mallard

I ported some of the new HIG material on to Mallard - you can find it in the hig3/ directory of gnome-devel-docs in git. I gather that HIG development is in a state of flux at the moment, but I'm hoping that providing some infrastructure for it will make things easier for the usability guys who're tackling the rewrite. There's a template for UI patterns in there too - working on a pattern could be a good way to start contributing to the HIG (hint, hint).

Cheesy sounds?

You know how Cheese can apply fun filters to your webcam feed? It might be cool to do something similar for your microphone input. I mean, really, who doesn't want to sound like Darth Vader from time to time? Is it possible to build something in GStreamer perhaps? It could make for a nice project for someone over the Christmas holiday season. Just sayin'...

DevDocs/Tools Hackfest day one; Handling lots of screenshots

DevDocs/Tools Hackfest day one

You find me, Phil "Sensible" Bull, seeking refuge from an uncharacteristic early-December British snow-apocalypse, in the warmer, sunnier climes of Berlin. It's -11 degrees C out there. My legs went numb for a while. But there's zebra steak (courtesy Openismus) and Internet (courtesy Openismus), so I'm happy (courtesy Openismus).

Today we spent a lot of time discussing the GNOME developer platform and "developer stories" (essentially, who is trying to do what with GNOME). It looks like a decent platform overview is a must-have, so we worked on stubbing one out, and discussing the roles of the various libraries and what they offer to developers. We have a really impressive platform, organised in a really confusing way.

A big project over the course of the hackfest will be the writing of a number of awesome* ten-minute introductions to various GNOME technologies. The plan is to have a handful of tutorials for writing interesting apps using Clutter, Telepathy, GStreamer and so on, which you can work through over a lunch break and which leave you enamoured with GNOME. It's pretty amazing what you can cobble together in about an hour - Johannes has made some sort of noise weapon, for example.

One particularly nice thing that popped out of the discussion was the identification of K-12 (school) kids as an interested developer user group. We have people out there using open-source tools to teach programming and we could be doing more to support them. Any ideas, folks?

(* Technical term)

Handling lots of screenshots?

If you're dealing with a lot of screenshots in your documentation, you might be interested in one of these tools:
  • Tuxtorial is a tool for producing image-based walkthrough tutorials. You can host your tutorials on their website.
  • QuickShot is an almost-automatic screenshot capture program, and supports translations.
Some types of documentation are well-suited to a heavily-visual approach (like walkthroughs), but not all of them. We tend to use screenshots sparingly in the GNOME and Ubuntu docs - overusing them distracts from the textual content, and they lose their power to highlight key points and illustrate things that are difficult to describe. That said, there are a few places where we should be making better use of them, but we haven't been because of the translation burden.

Misattribution; Berlin; Fun Paper

Misattribution: Who the hell is Paul Bull?

Berlin: I'll be in Berlin from the 1st - 7th December for the GNOME DevDoc/Tools hackfest. Come and talk to us about documentation/user assistance!

Fun Paper: Concentric circles in WMAP data may provide evidence of violent pre-Big-Bang activity, V.G. Gurzadyan and R. Penrose [note the scanned-in graphs]. In what was, for me, a first-rate bit of physics hobnobbing, I spoke to Roger Penrose about it last Friday: "The crazy thing is that it might actually be real" [paraphrased]. He also seemed vaguely impressed by its appearance on arXiv - he's never published a preprint there before, apparently.