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.

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.

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.

1. It’s easy (Yes, step one is, “It’s easy.”)
2. Click on this fancy link.
3. Look through the list of cities and find a city that is in the same time zone as where you will be on Sunday.
4. When you find a city such a city, look at the time that is listed next to it.

That will be the time of the meeting! You can join us in the #ubuntu-meeting channel on the freenode IRC network at that time, and we’ll have our meeting. We have a lot to cover, but we’ll prioritize things so that we only meet for an hour.

The focus of the meeting will be on the documentation team strategy document, as well as confirming our goals for the 11.10 release.

Hope to see you there!

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.

Here is a quick peek at what we are doing:

Click to play

This is all done with Mallard and Yelp.

KDE, you can have this, too. Talk with Shaun McCance. Shaun has revamped the back-end of yelp so that it wouldn’t be crazily difficult to put a Qt front-end on it.

Just imagine it . . . You could call it “kelp.”

As for the docs, there is still much more to be done. Join us on #ubuntu-doc on IRC, or join the Ubuntu Documentation team mailing list to see how you can help out.

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.

I ran into a couple of roadblocks in trying to use entities with Mallard recently, and thought I would share how I worked around them in case anyone else needed to do the same thing. Although my examples deal with Mallard, what I note here will also work for entities in DocBook 5 documents, or any other RelaxNG-based XML documents.

Entities?

Before I start, though, if anyone is wondering what I’m talking about when I say, “entities,” they are a handy variable-like feature of XML and a couple of other markup languages. For example, they allow you to type something like &exaile; into your document, and then have it magically parsed as:

<guiseq><gui>Applications</gui><gui>Multimedia</gui><gui>Exaile</gui><guiseq>

Using Entities in Mallard / RelaxNG documents

To set up and use entities in your XML-based document, you basically need three things. You need a file that contains the entities you want to use*, you need to declare where those entities are tracked, and you need to actually use the entities in your document.

The Entities File

Previously, step one was very easy. You would just create a file that contained values like this:

<?xml version="1.0" encoding="UTF-8"?>
<!-- MENUS -->
<!ENTITY abiword '<guiseq><gui>Applications</gui><gui>Office</gui>
<gui>AbiWord</gui></guiseq>'>
<!ENTITY about-me '<guiseq><gui>Applications</gui><gui>System</gui>
<gui>Users and Groups</gui></guiseq>'>

<?xml version="1.0" encoding="UTF-8"?>
<!-- MENUS -->
<!ENTITY abiword '<guiseq xmlns="http://projectmallard.org/1.0/"><gui>Applications</gui>
<gui>Office</gui><gui>AbiWord</gui></guiseq>'>
<!ENTITY about-me '<guiseq xmlns="http://projectmallard.org/1.0/"><gui>Applications</gui>
<gui>System</gui><gui>Users and Groups</gui></guiseq>'>

Out of the Woods

Once you make it past step one, the rest is a walk in the park.

Step two is to declare your entities in the start of your documentation files. I modified a DocBook 5 example to come up with this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE page [
<!ENTITY % entities-xubuntu SYSTEM "libs/xubuntu.ent">
%entities-xubuntu;
]>
<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="music">

Wrapping Things Up

Step three, using your entities in your documents, is no different than what you would have done with DocBook 4 or any other XML-based syntax. For example, typing &abiword; will be parsed as:

<guiseq><gui>Applications</gui><gui>Office</gui><gui>AbiWord</gui></guiseq>

and will cause “Application > Office > Abiword,” to magically appear in your rendered documentation.

If you have any questions, corrections, or suggestions (as I’m sure you’re all keen to be chatting about XML entities), feel free to leave me a note in the comments.

* I’m using external entities, which requires a separate file, but you can also use named or charater entities.
** Apparently the namespace of the parent node is no longer inherited by the entities, so you need to declare the namespace in the entity itself.

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.

Edit: I recommend checking out Paul Frields’ post about Emacs and nXML mode, and also looking at the Fedora wiki page that he created.  I think his approach is a bit simpler and cleaner than what I’ve provided below.  Feel free to peruse what I’ve written, though, as some of my links to “getting started” references should still be helpful.

From flickr user tsmall. Attribution-ShareAlike 2.0 Generic license

After perusing my options, I decided to try Emacs with nXML-mode.  Emacs’ nXML-mode provides real-time validation for RelaxNG-based documents, something which no other open source authoring tool provides. But while nXML-mode can validate XML documents on-the-fly, the default installation is not set up to validate against the recently-developed Mallard and DocBook 5 schemas.

Thus, to take full advantage of the latest in duck-based documentation technologies, I needed to modify my .emacs file and the nxml-mode files themselves.  What follows is an overview of exactly what I did in the hopes that others can make use of the same changes, too.

An nXML-mode foundation

Before we get started, though, you should know that much of what follows is derived from information on this website.  I encourage you to visit the site, as it provides an introduction to how nXML-mode is configured, and enough of an introduction to using nXML-mode to make you at least modestly productive right away.

Part One: Setting up your .emacs file

The first step in setting up nXML-mode for Mallard and DocBook 5 is to make a few changes to your .emacs file.  If you are new to Emacs, your .emacs file sits in your home directory, and serves as a personalized Emacs configuration file.  You may need to create the .emacs file if it doesn’t already exist.

;; /usr/share/emacs/site-lisp/tcc-nxml-emacs:  Add these lines
;;      to your .emacs to use nxml-mode.  For documentation of
;;      this mode, see http://www.nmt.edu/tcc/help/pubs/nxml/
;;--
;; Add the nxml files to emacs's search path for loading:
;;--
(setq load-path
      (append load-path
              '("/usr/share/emacs/site-lisp/nxml/")))
;;--
;; Make sure nxml-mode can autoload
;;--
(load "/usr/share/emacs/site-lisp/nxml/rng-auto.el")

;;--
;; Load nxml-mode for files ending in .xml, .xsl, .rng, .xhtml .page
;;--
(setq auto-mode-alist
      (cons '("\.\(xml\|xsl\|rng\|xhtml\|page\)\'" . nxml-mode)
            auto-mode-alist))

The above .emacs configuration tells Emacs where to look for detailed XML processing instructions, and also causes Emacs to automatically use nXML-mode for XML-related files.  (Did I tell you that Emacs might have a bit of a learning curve?  Yeah, that’s true.)

Part Two: Modifying the nXML-mode configuration files

The second step is to modify the nXML-mode configuration files themselves. This will add the appropriate nXML-mode secret sauce to handle Mallard and DocBook 5 documents.

Fortunately for you, I grabbed the latest nXML-mode source files from the nXML-mode website, and made the appropriate modifications myself.  You can download my customized nXML-mode files from this archive.

Here’s what I changed from the default setup:

• I added the docbookxi.rnc and mallard-1.0.rnc schemas to the schemas directory
• I modified the schemas.xml file, thus including the docbookxi.rnc and mallard-1.0.rnc schemas as part of the XML-validation process.

Note that I have used the DocBook 5 “docbookxi.rnc” schema which allows for xinclude functionality.  If you want to use the schema that does not allow for use of xinclude features, you’ll need to adjust the files accordingly.  The current DocBook 5 schemas are available here.

Part Three: Copy your nXML-mode files to the proper location
The final step is to copy the nXML-mode files to the proper location on your file system.  As indicated in our .emacs file, that location is:  /usr/share/emacs/site-lisp/nxml/.  Thus, you should copy all of the files in the downloaded “nxml” folder into that directory.  You will need administrative privileges (using root or sudo) to do this.

Wrapping up

That’s it, though.  You should now have a functioning nXML-mode environment that will allow you to fire-up Emacs and start writing Relax-NG-based documents, getting all of the real-time-validation features that Emacs provides. If you can think of any ways in which I could improve my approach, please let me know.  Otherwise, I encourage you to head-on over to the nXML-mode website, and view some of the nXML-mode information and resources that are available as you get started.