Notes from the Mousepad

I’m at the GNOME documentation hackfest in Brno, Czech Republic, and we’ve been updating help for GNOME platform and applications in advance of GNOME 3.4.

As part of the event, we’ve been reviewing our use of the Mallard syntax, making sure that we’re getting the most out of some of the new features. One newer feature in Mallard allows users to expand or hide portions of the help as needed. This helps users can more easily scan through possible topics, and to open the ones that are relevant to them. It also has the added benefit of saving space on the screen. This feature is in an experimental namespace for now, but we’re please enough with the results, and it is likely to be moved into the primary schema shortly. It will be in limited use in our help releases for the 3.4 cycle.

Here’s a brief example of what this looks like in action (note: you might need to view the page directly rather than through a feed aggregator if you want to see the video):

Also, here’s a portion of the code that makes it work. All that’s required is a the “ui:expanded” attribute on the appropriate element. It accepts values of “yes” and “no.”

<table rules="rows" frame="top bottom" ui:expanded="yes">
  <title>Tab-related Shortcut keys</title>
    <thead>
      <tr>
        <td><p>To Do This</p></td>  <td><p>Press This</p></td>  
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><p>Switch to the next tab to the left</p></td> <td><p>Ctrl + Alt + PageUp</p></td>  
      </tr>
    </tbody>
</table>

It’s possible to use this attribute on any element that contains a title, so you have the ability to use it on tables (as I’ve done here), lists, steps, or even entire sections. Thus far we’ve only used them on tables, and the style rules have yet to be ironed out.

The hackfest has been good thus far, but we still have much to do over the next couple of days. I am focusing on some updates to GNOME user docs, as well as writing new docs for Seahorse Encryption Manager, Rhythmbox, and am doing some GNOME docs team wiki work. Florian Nadge and Petr Kovar of Red Hat have been more than gracious as hosts, and the food on Brno is plenty meaty. Plus, there is cheap beer.

Of course the food and drink is even less expensive when Shaun McCance of Syllogist.net sponsors a dinner for us (thanks, Shaun!). Many thanks, as well, go to the GNOME Foundation for their sponsorship of our travel and accommodations.

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.

Here’s a few pictures from UDS:

Saying goodbye to Matt Zimmerman at the UDS opening keynote. It took me until Friday to thank Matt for his advocacy around women’s issues, as well as LGBT and gender issues. There aren’t many people in positions such as his who do so, so many thanks, Matt. Best of luck to you.

Jani Monoses and and Charlie Kravetz, the past and present leaders of the Xubuntu project. (Missing in this photo is Cody Somerville, who headed up Xubuntu in between the two pictured here. Also missing is Lionel Le Folgoc, who was surely off packaging software somewhere in France.)

The hotel’s grand ballroom, with the one and only Micah Gersten (micahg) in the foreground. He makes us all feel more secure when he’s around.

The bridge on the Danube at night. We had a lot of fun walking around and taking pictures that night.

Me giving a thumbs-up to the trip while going down one of the super-escalators to the train platform. (Credit to Lyz Krumbach for this photo – CC by SA 3.0 ftw).

More pictures (some of them fuzzy!) can be found on my Picasa page. Many thanks to Canonical for sponsoring my airfare and accommodations on this trip.

Now that my week at the Ubuntu Developer Summit is over, and I have completed my safe flight back, I thought I would write up a blog post about my experience while I complete my recovery from jet lag.

My week at UDS was a challenging week. A great week. A week in which I had great discussions around docs, met lots of cool people, and wound up expanding the limits of what are normally considered acceptable sleep patterns.

I had three docs-team sessions during the week. I also attended two sessions about cloud-related documentation, and another session on server documentation. The three docs-team sessions focused on the team strategy, our goals for the 11.10 release cycle, and evaluating a web-based documentation platform.

Team Strategy

The inspiration for the team strategy discussion is the Xubuntu Strategy Document. Have you read it? When Cody Somerville first wrote it, part of me was like, “Are you serious? Did you write this yourself?” It seemed too complicated. In practice, though, I’ve seen the Xubuntu team reference that document while making decisions time and time again. I think a similar document would benefit the docs team, too. I’m preparing a draft document based off of recent team discussions, and will be sharing it in the next week.

Team Goals for the 11.10 Release

The team goals session was pretty great. People in the room, and people listening in via the audio casts, gave helpful input. There was more focus on the Ubuntu wiki at UDS than I anticipated. Some of our goals for this cycle include creating a strategy document, contributing to upstream docs projects, refactoring our team wiki, testing of documentation accessibility, testing a preferred help layout, doing stable release updates for docs and translations, squashing boogs, adopting a consistent coding style, updating our style guide (or picking an existing one), and doing some of the initial work in revamping help.ubuntu.com.

It sounds like a lot, and it is, but some of it is already a work in progress. We will make these goals explicit during our next team meeting.

Web-based Documentation Platform

The group behind this project is Pronovix, a Drupal consultancy. I knew that their project was using Drupal and DITA, but I wasn’t sure what *their project did*. They had some of their staff based in Hungary, just a short trip away from Budapest, so I thought it was worth getting in touch to learn more about their approach and how it might benefit us.

DITA stands for the Darwin Information Typing Architecture, an XML syntax developed by IBM that specializes in content profiling and content reuse. The advantage of content reuse with a tool like DITA is that it allows you to write something once, write it well, and reuse it most everywhere. That is the idea, at least. Implementation of DITA can be difficult. Their project has promise, but the toolchain isn’t currently packaged by any distro other than OpenSUSE. Harald Sitter (Mr. Apache Log File) felt that this very much limits the likelihood of upstream adoption.

Even with that in mind, we are going to seriously evaluate their platform. It was very considerate of this group to make a trip to demonstrate their project, and we want to be supportive of everyone who is working in open source documentation.

There are quite a few irons in our fire, and we’ll have to get word out about our activities somehow. Our progress will likely be presented via a new Ubuntu Documentation Team blog. We think now is a good time to start one up, so look for more info on that soon, as well.

The University of Illinois at Chicago is once again planning to host their Flourish Open Source conference, and have put out a call for speakers.  The event will be held April 1-3, 2011, on the university’s campus on the near Northwest side of Chicago.

Though the conference is run by student volunteers, you wouldn’t know it judging by how well it is run.  This will be its fifth year, and each event has been well-organized, informative and fun.

For those who are interested in speaking:

Presentations are typically an hour long (including Q&A) and discuss
open-source-related matters of technical, community, or industry importance.
Past presentations have tackled a diverse array of topics – from kernel hacking and programming languages, to community/project management and women in open-source. If they get several proposals around a particular topic, they may opt to build a panel discussion.

Workshops are usually three hours long, and explore a particular topic in an
intensive, hands-on environment. In the past, Flourish has offered workshops
on Android, Websphere, Erlang, Processing, Plone and Drupal. The organizers
provide all necessary connectivity.

The organizers will be accepting proposals via their speaker proposal page up through the Christmas holiday.

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.

Here’s a quick rundown of some upcoming Free and Open-Source software events in the Chicagoland / greater-midwest area.

Saturday and Sunday, August 21 and 22, 2010: Barcamp Chicago

• Running all day and night this Saturday and Sunday
• 215 E. Ohio Street in downtown Chicago
• Numerous presentations, and a “BarCompany” startup hackathon

Sunday, August 29: Ubuntu Chicago’s Ubuntu Global Jam

• Socialize and work with the team on bug-triaging and fixing, documentation, and more!

Friday through Sunday, September 10th through 12th: Ohio Linux Fest

• Keynote presentations by Stormy Peters, Executive Director of the GNOME Foundation, and Christopher “Monty” Montgomery, creator of the open-source audio format Ogg Vorbis
• Tracks dedicated to getting started in Free and Open-Source software, Linux security, and so much more.
• For Ubuntu users, there will be an “Ubucon” during the morning and mid-afternoon hours on Friday.

Saturday and Sunday, October 2nd and 3rd: Barcamp Milwaukee

• A wide range of sessions relating to Free and Open Source software and general geekery.
• Like Barcamp Chicago, this event will run throughout the entire weekend, including overnight activities between Saturday and Sunday.

Saturday and Sunday, October 22nd and 23rd: Erlang Camp, Chicago

• A weekend devoted to learning how to confidently put Erlang code into production for your company, group, or individual project.

Events at the Chicago hacker space, Pumping Station One

• Check their calendar for their ongoing list of events and activities