Notes from the Mousepad

As I mentioned in a recent post, gedit snippets can help you write code more quickly, and with fewer errors, than writing all of your code manually. Snippets work by expanding small chunks of text into complete combinations of code boilerplate and variable/attribute placeholders. Using these pre-configured combinations of boilerplate and placeholders frees you to focus on the bits of code and text that are materially relevant to your work at hand.

You can enable the gedit snippets plugin by selecting Edit > Preferences > Plugins > Snippets.

There are four components to using snippets: confirming the language or syntax setting, entering the snippet ID, activating the snippet, and completing the snippet by entering the appropriate attributes or variables into the placeholder text areas.

The first thing is to make sure that the file type is set to correspond with the type of file you’re working on. If you’re starting from an existing file, gedit will attempt to set the file type for you automatically. If you’re starting a brand new file, or if gedit hasn’t correctly identified the file type, you can also manually set or change the file type.

Once you have that in place, the most difficult part is actually remembering the snippets that are available. You can view, edit, and create snipppets using the Manage Snippets window (see Tools > Manage Snippets). Once you know the relevant snippet IDs, all you need to do is type a snippet ID, and press the tab key. The tab key is what activates the snippet.

After you press the tab key, gedit converts that brief snippet of text into a combination of boilerplate text and appropriate variable or attribute placeholders. Pressing the tab key again will move the cursor to the next placeholder area.

Here’s an example. I’m starting from a blank page, and am writing a new Mallard XML file. The snippet ID to start a new Mallard page file is just the word, “page.”

Simple enough! Just enter the snippet ID, press the tab key, watch as gedit inserts the boilerplate text, and then use the tab key to maneuver through the placeholder areas.

There are currently snippets for numerous languages and syntaxes, but coverage of each language varies, and some snippets may not include the most recent language features. Give gedit snippets a try. If you don’t see a snippet feature that you’d like to use, file a bug in the gedit bug tracker.

I’ve been maintaining the gedit documentation since the run-up to the gedit 3.0 release, and doing so has helped me to get to know some of the ins-and-outs of the program. What can I say, it’s one of the perks of writing documentation – you get to know the software that you’re documenting.

With that, though, I thought I’d pass along some of the basic configurations that help me to write documentation more quickly, and in a more consistently-formatted way.

Here’s a quick run-down of some settings that you may find helpful:

View Preferences – Edit > Preferences > View:

• Check the following items:
• Display line numbers (this helps with locating validation errors)
• Display right margin at column (80 characters) (breaking lines at 80 characters makes diffs look prettier)
• Highlight the current line
• Highlight matching brackets (optional: I don’t use this feature, but some people prefer it)
• Uncheck:
• Enable text wrapping (not needed if you’re breaking lines at 80 characters)

Editor Preferences: Edit > Preferences > Editor

• Tab Width: 2
• Check
• Insert spaces instead of tabs
• Enable automatic indentation
• Uncheck
• Create a backup copy of files before saving (not needed if you’re using revision control, like git or bzr)

With regards to plugins, I recommend enabling the dashboard plugin (which will be available as part of gedit 3.4, included in Ubuntu 12.04, Fedora 17, OpenSUSE 12.2, etc.), and the gedit snippets plugin. In the near future I’ll be writing up a post about using gedit snippets.

One other neat feature that I often use with gedit is the keyboard shortcut for moving a line up or down within the text. If you position your mouse cursor on any point in a line, and then press Alt + Up Arrow, it will move the entirety of that line up within the text. Pressing Alt + Down Arrow will move that line down within the text. Simple enough! (The complete list of gedit shortcut keys is available in the user help, by the way. Just open up gedit and press F1.)

Do you have any suggestions or tips for using gedit to write documentation? If so, I’d appreciate you sharing them with me in the comments.

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.

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.

Recently Mark Shuttleworth wrote about how Qt will become part of the Ubuntu 11.10 desktop, and that Qt-based apps will eventually be considered as possible default Ubuntu apps. Obviously, this would be a big change from using GTK-only applications (that is, aside from Firefox and Open/Libreoffice applications), but Mark encourages GNOME developers to consider using Qt, too. He writes, “Perhaps GNOME itself will embrace Qt, perhaps not, but if it does then our willingness to blaze this trail would be a contribution in leadership.”

I agree on this, and think that enabling usage of Qt in GNOME projects would be a contribution in leadership. It would be great if developers had the option of using tools like Qt Creator and Qt Quick when building applications for GNOME-based desktops (or other devices!).

The question is: How do you make that happen? All technical matters aside, how do you encourage GNOME developers to consider using Qt for their applications?

To me, one major consideration in further developing the Qt-to-GNOME bridge, and encouraging developers to use Qt in GNOME-based desktops, involves copyright. I think the GNOME project, and its large group of developers, would be more likely to embrace Qt if Canonical did not put the dconf binding work (or other such Qt/GNOME integration work) under strict Canonical ownership via their contributor agreement.

The issue is that the contributor agreement gives all copyrights of the work (even contributions made by non-Canonical employees) to Canonical, and permits Canonical to relicense the work (even make it proprietary) at their discretion. To me, this would present a considerable risk for the GNOME developers and for the GNOME project.

The folks at Canonical have not yet indicated whether or not the contributor agreement applies, or will apply, to the early QT/dconf binding work. My thinking is that, if Canonical is disinclined to having the larger GNOME project use Qt, Canonical will request full copyright ownership of any Qt/dconf work. Thus, Canonical would “own the bridge” between the land of Qt and the land of GNOME, and anyone who wants to use that bridge would have to do so knowing that it could eventually be made proprietary.

Moreover, I think it would be a bit ironic if Canonical put the Qt/dconf work under their contributor agreement. As I understand it, Canonical’s main justification for requiring copyright assignment is that they “wrote the code,” for that project, and would like to maintain ownership of it. While folks at Canonical may have done the initial Qt/dconf bindings work, a primary reason that Canonical is even able to safely use Qt in their business is because Nokia opened up Qt, and removed the copyright assignment requirement from Qt contributions. Surely the Qt codebase, along with all of its associated tools, is much larger than any binding work (no matter how significant), so Canonical’s reasoning wouldn’t seem to be as applicable here.

However, if Mark and the rest of the folks at Canonical actually wants GNOME developers to embrace Qt on equal footing with GTK, they will either donate out the Qt/GNOME integration work to the larger GNOME community, or they will push the integration work upstream to Qt.

I’m hopeful that the folks at Canonical will choose either of the latter two options and make their initial Qt/Gnome integration work available under the same copyright-free terms that Qt has been made available to them. I agree with Mark when he writes, “it’s the values which are important, and the toolkit is only a means to that end.” While it may ruffle some feathers initially, having Qt as a viable option for development in GNOME-based desktops can only improve the free software ecosystem by giving developers more choices in the tools that they are able to use.

As a closing note, some of what I’ve written here is speculation and opinion, but if I’ve misunderstood anything, or if anyone can shed further light on this topic, please share a note in the comments.

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.