Shaun’s Blog

Last weekend, I attended the first ever Writing Open Source conference. With me were Milo Casagrande, Phil Bull, and Paul Cutler. Those guys have already blogged about the event. You should read what they had to say. Besides the four of us, there were twelve other attendees from various open source documentation teams. It’s amazing how many experiences we have in common.

On the first day, the mayor of Owen Sound came to visit us. She’s going to be participating in the Dancing For Life charity event this weekend. People were trying to get me to give her a waltz lesson, but it’s hard to give a dance lesson without a dance floor. (Plus, waltz is really not my dance.) In retrospect, I probably could have given her a connection lesson.

We all learned a lot. For the last two months or so, I’ve been keeping a notebook about documentation. Basically, it’s a brain dump of things I would tell somebody if I were to sit them down and teach them everything I know about building documentation within a community. After three days, my notebook doubled in size.

I got to show off Pulse and Mallard. Pulse was really well-received. It seems a lot of teams are looking for better ways to track their documentation. I get really excited about Pulse, so it was nice to get others excited as well.

There were a lot of DITA enthusiasts at the conference. Mallard and DITA occupy similar niches: They’re both moving away from DocBook-style books and towards topic-based documentation. The first question (which I expected) after I presented Mallard was along the lines of “Why aren’t you using DITA?”

The obvious advantage of using DITA is that it has a fair amount of industry uptake already. In my defense, I first conceived of Mallard back in 2004. At that time, I hadn’t even heard of DITA, and I don’t think it had nearly the popularity that it now has.

I have been trying to play with DITA since coming back. So far, I’m finding it has a serious lack of hands-on introductory material. As much of a bear as DocBook is, I was able to write my first document after 15 minutes with The Definitive Guide. After two days, I’m still wading through conceptual overviews in DITA.

Mallard is designed to solve a concrete set of problems. DITA can do a lot of things that Mallard can’t, but I’m not at all convinced that I should care about those things. I mean, DocBook can do a lot of things Mallard can’t as well, but after eight years, I’ve learned that most of things just don’t matter to us.

What DITA doesn’t do is what I consider Mallard’s single biggest selling point: dynamic organizational structures. This is critical to our strategy for downstream documentation. It also can produce some nice results for plugin-heavy applications. In fact, one of my primary use cases when designing Mallard was to make something that would work for the GIMP help.

We could probably build dynamic organization on top of DITA, but I’m not convinced it’s worth the effort. Besides capitalizing on uptake elsewhere, I have yet to see any concrete benefits to using DITA. I’m just not sold, and I don’t buy into the notion that I should be automatically sold just because others think it’s cool.

That said, I think we could have reasonably decent two-way conversions between DITA and Mallard. DITA people don’t generally seem to view DITA as a delivery format. So if people want to use DITA as an authoring format and Mallard as a delivery format, I don’t see any reason to put stop energy on that.

So I’ve been trying to learn DITA well enough to make those conversions. Documentation tool chains is what I do, both in Gnome and for a living for the next three days. And I have to say, I haven’t had an easy time of it. And that concerns me particularly because if I have a hard time, I can’t begin to imagine how tortuous it will be to any potential new contributors that come our way.

To their credit, quite a few of the DITA enthusiasts have offered help. They are a friendly bunch. We’ll see how things play out.

♫NP: Bongo Fiesta by Machito & His Afro Cuban Orchestra

Wednesday was my 31st birthday.  Instead of hiding from a tornado like last year, we actually spent the entire day on a movie set for the upcoming independent movie Leading Ladies.  And on Tuesday, our new Nikon D5000 arrived.  (Thanks to all the people who gave advice on the camera.)  What follows is a random collection of thoughts about the movie, interspersed with a random collection of pictures I took.  I wasn’t allowed to take pictures on set, so all the pictures are from the break room and rehearsal room.

My fellow extras waiting

Being in a movie involves a lot of waiting.  Multiple people have described it to me as “hurry up and wait”.  They’ll tell you to take five and only call you back in half an hour.  Or they’ll put you on set, and you’ll think they’re ready to shoot, and it’ll be ten minutes before they say “Action”.  On the other hand, they’ll sometimes tell you you’ve got an hour, and then be ready for you in fifteen minutes.  It wasn’t annoying or anything.  We were all there for the movie.  Just an interesting observation.

Virginia and Andrew juggle while they wait

Benji Schwimmer plays one of the lead roles in the movie.  If you’re into the WCS scene, you probably know who he is.  If not, you might know him from So You Think You Can Dance 2006.  If not, well, you should start dancing.  Benji has an amazing personality.  His enthusiasm is contagious.  Pretty much everybody involved with the movie was very nice.

Dancers practice during a break

Benji practices whenever and wherever he wants

Silke and I were dancing some west coast swing in one scene, while most of the crowd was watching Benji and Jordan Frisbee do a routine on stage.  And as glad as I was to get to do some west coast, to be perfectly honest, if I were at a club and Benji and Jordan were doing a routine on stage, I’d be watching.  All the other dancers are Lindy hoppers, so we were the only ones doing west coast.  For all I know, all our parts could end up on the cutting room floor.

Benji and Silke

Silke has more pictures up in her Picasa web album.

As an added bit of excitement, on Friday I put in my two weeks notice at Wolfram.  After I’m done at Wolfram, Silke and I are heading on a three-week road trip out West and back again.  And when we return, I’ll be starting something new and exciting.  Very exciting and memorable birthday week.  More details to follow.

So I’m looking for a good camera. I’ve got a little Canon Powershot, which I love for day-to-day picture taking. But I want a nice SLR. It’s something I’ve been wanting for a while, but Silke and I are planning a nice vacation in July, and that seems like a good excuse to buy one now.

I’d like the opinions from the peanut gallery.  I know a lot of Gnomers are photonuts.  I do want a decent camera with interchangeable lenses.  But bear in mind that I’m a total n00b, so I want something that’s going to be fairly easy for me to use.  And I don’t want to spend too much.  If the price tag has four digits, it’s too much.

I’ve heard good things about the Canon Rebel.  Thoughts?

We have a video of our wedding dance up on myrealwedding.theknot.com, and it was recently picked as a finalist for the best wedding video (bride’s pick) for 2008. The winners apparently get a free vacation. I like vacations.

Go watch the video and vote for us! You have to get an account and all that garbage, but isn’t a vacation for Shaun and Silke worth it?

Edit: Silke informs me you can vote once per day.

There is something that I’ve tossed around in my brain the last couple of days.  It’s not something I really have time to pursue, but I figured a blog post might inspire others.

My employer has an education group.  They travel around and give classes.  This not only helps build a stronger user and developer ecosystem, but it (presumably) is a source of revenue.

So what if Gnome got into the education business?  I don’t think there’s much room for user training (though I may be wrong), but developers are another story.  An education program could generate income for the Foundation (caveat: I have no idea about the legalities of income and non-profits.)  But it’s not just income.  It’s income as a happy side effect of something that can really push our platform.

So there are a number of ways an education program could be approached, and they’re not at all mutually exclusive.  One option is simple training courses.  We’d prepare materials for a certain pre-defined set of classes.  Educators would travel and give on-site courses.  We could probably pursue means of doing remote classes through the tubes.  Courses would be day-long affairs.  Perhaps some would be multi-day, but still short.  Developers would get a cutesy little diploma saying they completed the course.

The training course approach would suit a lot of people.  And it’s probably the least-effort first-start approach.  Another education possibility is a real certification program.  A cutesy little diploma from a single course is a gimmick.  You don’t do it for the diploma; you do it because your employer thinks their employees should get some training.  You don’t put it on your résumé.  A certification program, on the other hand, would involve more extensive study.  It would’t be done in a classroom environment, but we’d need to provide the study materials.  At the end, you need to pass some tests to get an honest-to-goodness certification.  With some good PR, employers might actually care about our certification.

Yet another option is to do education through educators.  I was recently pointed to teachingopensourc.com, a community of educators and enthusiasts who talk about using open source in education.  Perhaps there’s room for our platform in the actual classroom.  One could imagine a class on user interface programming being taught using Gnome.  For that to take off, it would seriously rock to have a textbook, which is a wholly different beast than a tutorial or reference manual.

These are far from fully fleshed-out ideas.  They’re things that I’m very interested in, and are near to my position as “the documentation guy”.  But for them to be anything more than random thoughts on my blog, somebody would have to really drive them home.

Way back when we imported the HIG into gnome-devel-docs, I had a hig-devel branch set up for Calum’s work on the next generation of the HIG.  Except branches in SVN aren’t really branches; they’re just separate directories we copy into.  And I very stupidly took advantage of this fact by making the hig-devel “branch” be just a mirror of the hig/C directory of gnome-devel-docs/trunk.

My fault completely.  I shouldn’t have done that.

Now I’m trying to find a way to fix this branch in git.  If I just merge master into hig-devel, it basically blows everything away.  Git has no way of knowing that it should apply changes from some completely unrelated files that don’t exist in master.

Worst case scenario, I suppose I just do the merge, copy the hig-devel versions of all the files in, and commit.  Anybody have any ideas on how to do this in a way that preserves some history?

I’ve got some exciting stuff brewing with Pulse, my pangalactic project tracker. But I’m stashing things away on for a short while. Phil Bull, Milo Casagrande, Paul Cutler, and I are attending Writing Open Source: The Conference in June. (More on that in a soonish blog post.)  What this means is that Mallard needs to be working in Yelp by June 11, so Pulse is getting momentarily shelved.

Summer of Code

Just because I’m shelving Pulse doesn’t mean it won’t be worked on.  Florian Ludwig has been accepted to work on Pulse for the Google Summer of Code.  Congratulations to Florian.  While I won’t be doing a lot of active Pulse hacking, I will do my best to be a good mentor.

Florian is going to work on integrating bug tracker support into Pulse.  The obvious bug tracker is bugzilla.gnome.org, but the goal in Pulse is to have a generalized framework.  Hopefully we’ll be able to build on his work to link Pulse up to other bug trackers.

Architecture

Recently, I split all of Pulse’s module-processing code up into small plugins.  I’m really happy with the result.  After the refactoring, I was able to add support for the Evolution Quick Reference Card with a 250-line plugin.  (Don’t be fooled by what you see on gnome.org.  Activity and translations do actually work.  I just don’t have all the data uploaded.)

This got me thinking of how I could do the same thing to the front end.  What I’ve been toying around with is splitting all the tabs of pages off into separate applications.  So there would be, for instance, an application that provides the fancy activity graph page for modules and documents and people and whatever else.

The way it exists in my head, applications will be able to interact in ways other than just adding tabs.  One thing I was thinking of was an application to add notes to any object.  Hopefully I can remember what I was doing when I come back to it in a couple months.

Zukunft

So where this is all heading is Pulse becoming a bit more active as a collaboration tool.  It still has a very strong emphasis on automatic tracking, and always will.  But I’m starting to think of ways it can be extended to meet different people’s needs.  I think I’ve stumbled into creating a really nice tool, and I’d like to see it grow.

We will be having a documentation team meeting this Sunday at 17:00 UTC.  We will discuss Mallard and the future of Gnome documentation.  If you’re interested in what the documentation team has planned for Gnome 3.0, please join us.

I thought it might be useful to write down my goals for the following year somewhere public. That way everybody can hold me accountable. Here’s what I hope to accomplish by this time next year:

• Complete Mallard, the system that will allow us to write better user help more effectively.
• Get Pulse running in a production setup to allow us to better track our documentation.
• Completely revamp the User Guide, Accessibility Guide, and System Administrator Guide.
• Systematically review and improve all of the API references in our Platform.
• Rewrite the Documentation Handbook and the Style Guide.
• Update the Platform Overview.
• Nag the appropriate people to get a new version of the HIG.
• Drive the development of a hands-on tutorial (roughly 200 pages) on programming with Gnome technologies.

Can it be done? I hope so. Because all that stuff combined would seriously rock.

Update: Added lots of links.

The years are slowly starting to catch up with me. For the first time in my life, I have glasses. My distance vision is still incredibly good, but the glasses help for reading, or for staring at the computer screen all day. Obligatory screenshot:

Shaun in glasses