Notes from the Mousepad

I’m attending the WritersUA conference in Seattle this week, and yesterday was day one of the conference.  The conference started with Scott McCloud talking about how he created his Google Chrome comic, and I attended other talks on ISO documentation standards, as well as architecting your content so it can be reused.

McCloud’s talk was interesting in a number of ways, but one aspect of it that struck me was the volume of work went into what he did.  The initial basis of the work was 10 dvd’s worth of recorded interviews with developers.  They did not allow the content of the comic book form to be dictated by some kind of marketing storyline.  The comic still stood up as a form of documentation.

Additionally:
* The use of bubbles as text-placeholders in the comic created some difficulties for translators, but they were able to make things work. He didn’t provide a great amount of detail about this.
* He loved the mash-ups that resulted from the work being licensed under a Creative Commons license, even if the mash-ups didn’t follow the letter of the license.  Google did not attempt to sue people who made these mashups for noncompliance with the license.
* He demonstrated how comic book framing can keep the use focused on one item at a time, and make it easier to explain difficult concepts in an elegant, easy-to-understand way.
* I think he referenced XKCD at least 3 times.  He likes it.
* I can’t draw comics.  :/  Maybe I can use some of this stuff with screenshots, though.

I also attended a session on ISO standards for documentation and D.I.T.A., an open-source documentation toolkit similar to docbook.  The standard is maintained by OASIS, a not-for-profit standards organization – it looks great!  We got to see snippets of it, but it costs about $200 to get a single copy of the standard. :/  Even members of the OASIS committee who volunteer to maintain the standard have to pay to get a copy of it.  I am glad that at I don’t have to pay to contribute to Ubuntu.

The best session of the day for me was the session on architecting documentation for reuse.  The Ubuntu documentation team already has some of our content architected for reuse; for example, we use docbook “entities” for repetitive items such as system and software version numbers, Ubuntu website urls and certain procedures, but this showed how it’s possible to do more.  I’m a little green as a member of the Ubuntu documentation team, but I’m eager to learn more about this approach.

As I’m sure is the case with other Ubuntu-related development groups, the Xubuntu team has been quite active as of late.  We spent some time this weekend testing out configurations of system settings now that we have migrated to Xfce 4.6 for the 9.04 release, and have completed the transition to the new artwork for the release, too.  Much of these discussions took place over IRC, and it was fun to be a part of it.  We were able to hammer out patches, test them out, and then provide feedback to each other based on our findings.  The time spent proved to be very beneficial, and the Xubuntu 9.04 release is shaping up very nicely.

I’ve also been working on the documentation for Xubuntu 9.04, which has been rebased off of the Ubuntu 9.04 documentation for this release.  What this means is that I’ve been able to use bzr to merge in changes from the Ubuntu documentation as they happen, applying them directly to the current branch of Xubuntu documentation.  This is different from prior Xubuntu documentation efforts that had been based off of a much earlier set of Ubuntu docs.

In that sense, I was starting at a bit of a disadvantage – each release brings changes and updates, not only to X/K/Ubuntu itself, but also the associated documentation.  However, by using the current branch of Ubuntu docs as a starting point for this release, and merging in updates as they get applied to Ubuntu documentation, I’ve been able to leverage the ongoing contributions of the Ubuntu documentors and keep the Xubuntu docs more up-to-date.

Using this approach took a little bit of experimenting to find a good workflow for myself, but Bzr has proved to be a more-than-adequate tool for this particular scenario.  For example, the bzr command that I’ve used most frequently as of late involves merging in the specific changes from one Ubuntu documentation revision to another into the Xubuntu documentation branch.  To do that, I’ve just reviewed recent changes to Ubuntu documentation, navigated to my local folder of the Xubuntu documentation branch, and issued a command similar to this one:

bzr merge -r211..212 lp:ubuntu-doc

Here I’m telling bzr to merge in only the differences between revisions number 211 and 212 from the Ubuntu Documentation branch.  Merging in changes between specific revision numbers allows me to cherrypick – I can merge the changes that I want, and skip the changes that I don’t want.  This is helpful because Xubuntu docs will not include the Ubuntu Server Guide (my apologies to Adam Sommer, who has done a ton of great work on the Ubuntu Server Guide for this release), so I have skipped revisions that include updates to the Server Guide.  : /

If there are no conflicts between the merged files, bzr just identifies the changes as modified files – no problems.  Files that contain conflicts are identified by bzr, too, and it is up to me to resolve those conflicts.  Once fixed, I can then use bzr to mark the conflicts as resolved.  The process still requires some manual review on my part, but reviewing someone else’s changes is much easier than writing my own stuff, and gives me more time to focus on documenting the elements that are specific to Xubuntu.

I’m still writing additional documentation that is specific to Xubuntu, but have a little bit of time remaining before string freeze.  : )  At the end of next week, I am going to be travelling to Seattle to visit a friend and her husband, and also attend a documentation conference out there.  I’m going to focus on the Design Strategies, Content Development, and Open Standards tracks.  It should be a great time, and should make for a great learning experience, too.