Notes from the Mousepad

With both a two-day conference and a three-day sprint, the Open Help Conference made for a busy week, but I must say that it was a success. We had people there from Gnome, Mozilla, OpenStack, Red Hat, BSD, as well as people who were interested in learning about open-source help. Everyone had something to share.

Some of our discussions may bubble-up as other blog posts, but a couple of the presentations and discussions made me think more about engaging users where they are. They made me think of how we can do more to extended help to people who use our software in the places that they go, rather than just requiring them to seek-out help from our help platform.

Twitter as a support tool
For example, one topic that we discussed was using Twitter as a support platform. Jennifer Zickerman demonstrated Mozilla’s Twitter-based “Army of Awesome” as a facilitator for user-to-user support. It’s pretty cool that Mozilla opens up their support channels in this way — users help other users directly, and you only need a Twitter account to help out. Although you can’t always solve a problem in 140 characters, it’s easy to point someone to a support article or to suggest other help resources. In a less formal way, I’ve also seen members of the Mozilla documentation team use Twitter to request a technical review of new help articles, or to remind people about documentation-related events (e.g., reminders for Mozilla’s Wiki Wednesday events).

Stack Exchange sites: Likes and dislikes
Another approach that we talked about were the various Stack Exchange sites. In talking about this, we liked how good answers rise to the top (as opposed to regular user forums where you may need to scroll through rows of posts to find a solution to a problem) and the gamefulness of the sites. We also liked that user questions and responses are available for download in XML format under a CC-by-SA license (albeit with fairly stringent attribution requirements). In particular, the XML downloads of user questions will allow documentation contributors to see what questions users are really asking, and what questions are occur frequently.

This being an open help conference, some of us did note that the back-end for any Stack Exchange site is proprietary, and discussed the network-effect of how using closed-source tools encourages more people to use to closed-source tools. Yes, Stack Exchange sites are “free-as-in-beer” to the people who use them, but we discussed both OSQA (GPL-licensed) and Shapado (AGPLv3-licensed) as open-source alternatives that would be worth considering for similar help-site deployments. Someone also mentioned that Reddit (which isn’t necessarily a help platform, but is open-source software) is a popular area where people can post questions or comments that are related specifically to Gnome or Ubuntu.

Using blogs and planets to recruit writers
Aside from Twitter-based tools and Stack Exchange sites, some other ways of seeking out users are less centralized. Two items I took away from Anne Gentle’s talk were that she is not shy about asking bloggers to repurpose their blog posts for use in the official documentation, and she also recruits people who post to the OpenStack Planet to help write documentation. These approaches seem especially helpful when writing documentation for very technical and complex projects. In some areas, the help author may not have the deep domain expertise needed to write docs for bleeding-edge software.

Other possibilities, and the remaining need for good docs
One project that I’m curious to know more about is the Mozilla Sumo project. I wish that members of their team had been able to join us. Sumo seems like a well-rounded platform for gathering user contributions to official documentation, while still allowing for editorial review and for document translations.

Even with all of this in mind, though, I still see strong, centralized documentation as very important. After all, it can save a lot of time if a user can find good docs in one central spot, and even Google isn’t helpful if no one has documented a well-researched solution to a problem. These discussions reminded me that it’s also important to interact with users where they are, though. If you have ideas for other ways to interact with users where they are, or know of something that has worked well for you, feel free to share any suggestions in the comments.

I’m in Cincinnati in advance of the Open Help Conference, an event organized around open source docs, and the building of community documentation efforts in commercial projects. The conference will kick-off this evening with a social event, and will continue (with both the conference and post-conference docs hackfests) through Wednesday.

The event has some great speakers lined up, with speakers from Mozilla, Red Hat, BSD, GE, and others. Scott Nesbitt from DMN Communications will also be here. I’m looking forward to interacting with everyone, and am especially looking forward to talking shop with Anne Gentle. Anne works as the “Content Stacker” (aka documentation lead) for OpenStack. OpenStack shares our Launchpad infrastructure, so it will be great to find ways to collaborate with her and the other OpenStack doc contributors.

I will provide a few updates on the conference over the weekend on my blog, but you can also get some updates by following the #openhelp hashtag on both twitter and identi.ca.

I’m looking forward to a great weekend.

Although I’ve primarily worked on Xubuntu documentation in the past, this cycle has seen me contribute quite a bit to gedit documentation. Unfortunately, I’ve asked, and the gedit team isn’t going to be making an additional release for the 2.3x branch, so these updates won’t be included in Ubuntu 11.04. : /

Update: I’ve spoken with another gedit developer, and have been given the ok to get the 2.3x docs updated once the 3.0 docs are ready. Obviously, 3.0 is the priority, but I will make this happen for Ubuntu + OpenSUSE. : )

For now, though, I’m at the Gnome 3 documentation hackfest with Phil Bull, Shaun McCance, Johannes Schmid, Tiffany Antopolski, Natalia Ruz, and Germán Póo-Caamaño. Scott Nesbitt of DMN Communications and Words on a Page fame plans to stop by over the weekend, and Ryan Lortie has been playing the part of gracious local host, doing airport pick-ups and coordinating our hotel stay / work locations. (Thanks, Ryan!)

So, what are we doing here? The primary focus for Shaun, Phil, Tiffany, Natalia, and myself is to re-work the Gnome User Guide for Gnome 3. We are using the Mallard syntax to write more topic-focused help, addressing specific needs of users rather than providing help in a long-form manual format. We’re currently on day three of the hackfest, but we have three and a half more days to go. We will need every day–there is still much to cover.

An additional focus of the hackfest is to write Gnome platform and developer documentation. This is primarily the focus of Johannes and Germán, but Shaun will be helping with this as well. Thus far, Johannes has been working on implementing Gnome-related programming tutorials in several different languages. Some of his tutorials feature sounds, and we hear bleeps and bloops coming from his laptop every now and then . . . he’s making some pretty good progress.

Some of you may recognize Phil Bull’s name, as he is on the Ubuntu doc team, too. That means two Ubuntu users contributing to upstream Gnome documentation. Phil is even writing parts of the shell documentation from within Unity. (Ok, he looks over at my laptop which is running Gnome 3). But still . . . Group hug, Ubuntu / Gnome. Group hug.

Finally, I know the rule of “pics or it didn’t happen, so here are a couple of images to tide you over for now.

(Yes, I know that the pics are a little too big for my blog settings for now . . . I’ll have to fix it later.)

Thanks to the Gnome Foundation for sponsoring my hotel stay, to Syllogist.net for the muffins in the morning, and to Seneca College Centre for Development of Open Technology for providing the space.

Here’s a somewhat quick run-down of some projects with-which I’ll be participating, and some other projects that, while I might not be a direct participant, I am curious to watch develop.

Xfce Updates

I see the LXDE project get a good amount of attention lately, in large part (I think) because it uses somewhat less memory than Xfce.  Xfce is still going on strong, though, and plans are in the words for the eventual release of Xfce 4.8.

Jérôme Guelfucci recently provided a brief update on what’s going on with Xfce, and one of the big things is a push for updated documentation.  I’ll be contributing to that, and will likely be borrowing some of the user-help topic “stubs” that have been put-together by the GNOME Documentation team.  I’ll be sure to share any relevant topic stubs with them, too.

Jannis Pohlman has also started the process of forming an Xfce foundation.  Jannis notes that this would make Xfce a legal entity with a board of directors, and that it would help to raise funds through sponsors and other contributors for hackfests and other events.

My Documentation Projects

Lately I have been continuing work on gedit documentation and have also done some initial work on updating the Ubuntu Packaging Guide.  I should have the gedit docs well-drafted within another week or so, but I welcome suggestions and contributions with regards to the Packaging Guide.

Thus far, I’ve drafted the Packaging Guide in Mallard, and although Mallard is XML-based, it is much simpler than DocBook.  It is not difficult to learn, and you can draft-up a nice-looking, topic-focused documentation set with it rather quickly. I also know that there was a UDS session about the Packaging Guide today, so I welcome any feedback that resulted from that session, too.

Other Documentation Projects of Note

In non-Linux-help news, there are a couple of interesting DITA-related projects that I’ve been wanting to mention. If you haven’t heard of it before, DITA* stands for the Darwin Information Typing Architecture, an XML-based syntax originally developed (and later open-sourced) by IBM. The toolkit that processes the syntax, the DITA Open Toolkit, is Java-based, though, which I think has somewhat slowed its adoption in the Linux community. (Currently, only OpenSUSE packages DITA and the DITA Open Toolkit, but their implementation is a bit broken, perhaps due to an outdated version of Saxon in the OpenSUSE repositories.)

When people ask me what the big deal is about DITA**, I like to point them to this white paper (PDF).  It seems to provide a pretty clear picture of what DITA can help you do, even if it does make it look easier to implement than it is in real life.

There are a couple of DITA tools on the horizon that look to make it a bit easier to work with, though.  A group of Drupal developers are working with DITA developers to build a Drupal-based DITA authoring platform.  From what I can tell, it will be released under an open-source license.  They are just in the planning stages now, but I’ve relayed the Ubuntu Documentation / Ubuntu Manual / Ubuntu Learning Team’s requirements from what we talked about this past summer when considering the Ubuntu Learning Center.

Also, Don Day, the chair of the OASIS DITA Technical Committee, has put together a Free-as-in-Freedom web-based DITA platform.  It’s in its early stages, too, but you can get a look at it here. You can log in as a guest, and then select topic tools from the bottom of the page to have a go at editing the document.

A Docs Conference?  In Ohio?

Finally, there is word on the street about the possibility of a docs conference in Cincinnati during the first weekend in June.  I’ve expressed interest in helping with planning and organizing that conference.  For now I will keep my calendar open, and will post more news here as conference plans solidify.

*Whenever you do a Google search for DITA, it’s typically a good idea to exclude the phrase “Von Teese” from your search query.  That is, unless you want your documentation searches to also include results for a fabulous burlesque dancer / entertainer. If you do want dancer / entertainer results in your documentation search queries, then make sure to include the phrase “Von Teese” in your queries.

** Generally, people do not ask me about DITA.

This site lists who they’ve identified as the top 50 technical writers on the web, which I stumbled upon via a link from Scott Nesbitt’s blog.  While this list will certainly provide me with additional documentation resources, I notice a dearth of open-source documentation names in that list.  No Shaun McCance, no Emma Jane Hogbin, no Matthew East, and certainly no one with a name as cool as Milo Casagrande.

Paul Cutler, a member of the GNOME documentation team, has said that he wants to make documentation cool again.  He used some different phrasing (ok, he actually said, he wants to make it “sexy,” again, but I don’t really feel like going there), but what I take his comment to mean is that he wants to make documentation something that people see as technically innovative and relevant to users, even if most users instinctively turn to Google as their first line of support.  After all, Google’s search results don’t just grow on trees – the content that comes up in all of those search results has to come from somewhere.  Why shouldn’t the answers to user questions come from carefully prepared and researched documentation?

I don’t say this to denigrate blog posts, forums, or IRC support networks – that’s where users get most of their support these days.  Comprehensive documentation has its place, though.

With that in mind, I’m making initial, but steady progress on the Xfce 4.8 documentation, and really want to improve the Xubuntu documentation.  (I’m actually a bit ashamed of its current state given the beauty that is the rest of Xubuntu 9.10.)  I will be at UDS (though, unfortunately, only for the last two days), and look forward to meeting with fellow doc-team members, and anyone else who would like to discuss documentation and translations.

Per Daniel Holbach’s recent blog post about the Global Bug Jam, I thought I’d add my two cents (or give you a penny for my thoughts, and donate the additional penny to charity) about what the Ubuntu-Chicago Local Community Team is planning for the Global Bug Jam.

There are still quite a few details for us to iron out, but we have the basics in place, and are gearing up for the event.  What have we done so far?  First, we’ve been able to secure a great location, the headquarters of Centro – an online media services company in downtown Chicago – for the event.  Centro uses a lot of FLOSS tools in their development, and they’ve been a consistent supporter of FLOSS events in the Chicagoland area for a number of years, so we’re really grateful to them for allowing us to use their space.  (As a side note, one of their developers who helped to secure the location for the event is also the creator of “Open Sprints,” an GPL’ed indoor bike-racing application that has garnered a lot of enthusiasm amongst the bike messenger crowd in the U.S.)

Ok, so we have a location.  We also have people who are going to attend.  Those people have (for the most part) been prepped on what we’ll be doing.  We held an introductory session as part of a Chicago GNU/Linux User Group meeting a few weeks ago, where we were able to set people up with Launchpad accounts, PGP keys, SSH keys, and the 5-a-day application.  For those who weren’t able to attend the meeting, I’m sure we’ll be able to set them up online in advance of the event, or when they arrive for the bug jam.

Also, I mentioned it briefly above (“We also have people who are going to attend…”), but we are expanding the ranks of our loco team for this event.  Ubuntu-Chicago had been relatively quiet for a while, but we’re doing what we can to involve people outside of regular X/K/Ubuntu users and developers in the bug jam.  One of the better things to see in this process is how members of the Chicago GNU/Linux User Group are joining in, and how we’re also getting involvement of people who develop for FLOSS projects, but who aren’t typically involved in local Ubuntu events.  (They don’t even have to use Ubuntu . . .).  For example, I have heard of one Miro developer plans to attend portions of the bug jam, we hope to get some folks from Banshee and GNOME . . . and I’ve even heard that the entire Tilda development team (ok . . . so it’s just one person) may be involved, too.

Personally, I’m going to do my best to advocate testing and bug triage of Xfce 4.6 during the event.  I’m also excited that there will be a Lou Malnati’s Pizzeria DIRECTLY ACROSS FROM OUR BUG JAM LOCATION.  OH HAI, UBUNTU-CHICAGO CAN HAS TEH BEST PIZZA.

So, yeah, if you’re a X/K/Ubuntu user or FLOSS-coder who lives in / around Chicago . . . even if you’re not an expert . . . Check out our wiki page (with the new NavBanner that I ganked from the Massachusetts team), join our mailing list, and make plans to see us the weekend of February 20th. 

Things seem to be moving right along in Xubuntu-land.  We’ve scheduled regular meetings for the Xubuntu team for the remainder of the Intrepid release cycle, have posted them to our wiki, and have passed along word to the communications team for inclusion of the meeting dates on the Fridge.  Having regularly scheduled meetings helped keep us moving along during previous cycles so I am confident that having our meetings scheduled well in advance will do the same for us here.

We have yet to complete our agenda for the upcoming meeting, but one item that will be included is discussion of the new website.  I’ve passed along a draft project plan to Cody Somerville, and he seemed to like what I had prepared.  If we go by what I’ve prepared, we’ll have an internal team of Xubunteros to start things off, and will have an external team of interested, able parties to assist us once we’ve laid the ground work.  Again, I’ll be posting further details once we get that plan in order.

Of course, you could always just show up to the Xubuntu meeting to discuss it with us.  :]

In other news, we are considering using Yelp to display Xubuntu documentation, primarily to limit the discrepancies between common Xubuntu and Ubuntu documentation.  Of course, Xubuntu would still have its own set of Xfce/Xubuntu-specific documentation, but we would be able to base our documentation on the primary base of Ubuntu docs.  One part of the reason for this possible move is that Xubuntu doesn’t have very many system-doc contributors, and adapting the documentation from Ubuntu to Xubuntu is pretty time consuming, but there are technical and content-based reasons for the possible switch, too.

Why is it time consuming?  The root of the matter is that yelp uses special “ghelp” links within the documentation, but the Xubuntu documentation is currently presented in Firefox.  Firefox cannot display ghelp links, so we have to convert all of the ghelp links to accommodate our use of Firefox.  Of course, modifying links is not so difficult, but the linking differences also necessitate that a different structure be used for the documentation files.  In fact, the Xubuntu documentation currently gets validated as one large meta-document based off of the initial index.xml file, and this is not valid docbook.

Relying on Yelp and adapting our documentation later in the release cycle would also allow us to leverage the numerous contributions that are made by the hoards of crazy documentors that submit patches for the Ubuntu system documentation.  Going that route would make it so the Xubuntu docs would be more accurate and comprehensive in terms of the documentation’s relation to the final released product.  More accurate and comprehensive documentation == more awesome documentation.

As a final (seemingly unrelated, but nonethess important!) note, I’d just like to point out the great work that Cody Somerville and some of the other Xubuntu / Xfce contributors have been doing.  For one, Cody took over as the Xubuntu project lead in the early Spring, and has been doing some pretty remarkable work.  He’s not only doing a great job in terms of his own activities, but is doing a great job of enlisting and encouraging the help of others.  I would also like to thank Lionel Le Folgoc and Jérôme Guelfucci for their remarkable packaging and bug triage work.  It looks like Jmak is getting a good start on the artwork for this release, too.

Neato burrito.

Cody Somerville has been writing quite a bit lately about what’s going on with Xubuntu, focusing a lot on the strategy document and some technical goals for the next release, but we also have a couple of other things in the works – some items that are kind of on the fringes of the distro, but important nonetheless.

One item is an update to the website.  Xubuntu.org is in need of a refresh!  We’ve had a couple of starts and stops on updating it over the last two releases, but nothing noteworthy ever came of it, so this time I’m putting together a project plan that will break the tasks down into smaller chunks with a clear plan for getting things in place.

I’m not going to guarantee that things will work like clockwork, and I’m not even sure who we’re going to get to help out with the website, but I figure that setting a plan with individual bits that people can do one-by-one is more likely to garner success than handing someone the keys to a base Drupal installation and saying, “Have at it!  Let us know when you’re done!”

I’m sure I’ll have more news on that once I’ve got the basic project plan in order, and (of course) we’ll be seeking out help with the website then, too.  If you think you might want to help out, please make a note of it – place a bookmark in the Firefox 3.0 of your mind.  :]  Or you can just read this blog aggregator thingy, and look for more info about the website project plan when I write about it.  Perhaps that would be better than trying to integrate Firefox 3.0 with your brain.

For now, though, work continues on adding poetic, beautiful content to the wiki, and a few documentation ideas are being tossed around amongst Xubuntu folks.  It’s kind of hard(y) to believe that the first Alpha release for Intrepid is less than a week away, but I suppose it’s how things go.

The Xubuntu documentation for 8.04 is done, and the doc-centered folks are now working on updating the wiki.  There are still quite a few holes in it for now, but we’re working fairly quickly.  I like the new menu bar.  It makes it easy to get around.

Also, I know it’s not much notice, but tomorrow (Wednesday, 2008-03-26) Jono Bacon is leading a Xubuntu-focused meeting in the #ubuntu-meeting channel on the Freenode IRC network.  The meeting will be held at 1900 UTC (2pm Chicago time).  We’re going to discuss Xubuntu’s mission and strategy, and discuss how to pull in some additional development and packaging help.  The Xubuntu team has had a bit of turnover as a result of some internal disputes over default package selection recently, and we think that coming to some kind of a consensus on our project goals will help focus our efforts and help put some of the conflict to rest.

I feel like Xubuntu is moving in a good direction, though.  Cody Somerville looks to be the person who will be leading the project, and he has a good idea of what Xubuntu is about, is technically proficient, and knows how to argue a point rather than getting mixed up in a bunch of jibba jabba.  All good qualities to have in a project leader.  (Cody also made that wiki menu bar on the Xubuntu wiki.)  As much as anyone pays attention to a wiki, perhaps having a well-set wiki with clear paths to help people start getting involved will help things along a little bit, too.

I’m preparing an interblags post that will contain 8.04 reasons for why Ubuntu and Kubuntu users should consider using Xubuntu (it might be more like 8.04 reasons why I like Xubuntu . . . I’m not sure), but it’s not ready yet.  I only have 7.04 reasons so far.  My post should be Hardy, not Feisty.

The Ubuntu documentation team has recently migrated all flavors of *Ubuntu documentation from Subversion over to Bazaar.  There are now separate branch repositories for each of the flavors, and instructions on how to download the repositories (and how to submit your changes) are up on the Ubuntu wiki.  Thanks to Matthew East and a few others for their work in getting this set up.

The Xubuntu documentation turned out ok for the Gutsy Gibbon release – it was certainly much better than it had been for the Edgy and Feisty releases, but we still didn’t reach our goals.  We did a lot of work on the docs, but without the efforts of Luzius Thöny at the very end, I don’t think that the docs would have been shippable.

Xubuntu Hardy Heron (Xubuntu 8.04) will be a long-term release, so I want to make sure that the documentation is top-notch.  The good news is that we already have a good base to work from (we don’t even have to copy everything over from Ubuntu from scratch like we did before), and we also have some people who have some documentation experience under their belt now.  This is good.

I’m not sure how else I’ll be able to contribute to the Xubuntu effort this time around.  I’ve started a new job that is more demanding than my prior jobs, so that has to take priority.  I’d still like to contribute to Xubuntu, though.  I enjoy it, and the people involved with the project.