Why I enjoy writing user help for GNOME

It’s been almost ten years since I started contributing to open source projects.  One of the big ways I’ve contributed in the past is writing user help.  Not knowing how to code then (and still really don’t know now, as hard as I try to learn Python), writing is something I enjoy and an area where I think I can make a difference.

There are a number of different places to apply a writing skill in open source.  You can write release notes, marketing copy, websites and the help documentation for an application.  Writing user help is one I enjoy.

I want to say that writing help is easy – but what’s easy for me, may not be for others.  Those who write an application might say it is easy for them – but as I’m learning, it’s not easy for me.

You can debate who might want to use a Linux desktop and not use Microsoft Windows or macOS.  To me, there are a few different use cases:

  • Developers.
  • Hobbyists.
  • Users in developing nations.

It’s these last two groups that I think having up to date user help is important. Using a Linux desktop, such as GNOME, can be a big change and paradigm shift for a user.  In developing nations, they may not be able to afford a Windows license or the applications they might want to run on Windows.  For example, Photoshop isn’t cheap – but GIMP is free.  If you’re switching to a new operating system, there may be things you don’t know how to do and if there isn’t user help available, how else are you going to learn?  Especially if you’re an area that might not have good internet access.

But having started to learn to code in the last year, I understand why developers don’t write help.  Even with my terrible skills at writing code, when I’m writing a function in Python, I’m not documenting my code as I should be, much less writing a document about how to use the finished application (if it ever gets finished).  You get in the zone and just write code and tell yourself you’ll get to it later.

But on the other hand, when I start an application and can’t figure out how to do something, my first step is to see if I can figure out how to do it myself.  I’ll check to see if there is help built into the application, if not, I’ll check the website.  Having come back to using GNOME a month ago, I was dismayed to find an application I was excited to use to not have either when I was trying to figure out how to use a feature.  (I won’t shame them publicly, and no, they aren’t an application created by GNOME, it’s an actively developed application available on Github).

Although I’ve been using macOS for the last few years, it’s not as if I stopped using open source.  I have open source applications running on my Macbook, a laptop running Fedora though I didn’t use it much, a server at home also running Fedora, and Digital Ocean droplets running CentOS and Fedora.  I strongly believe in open source and love that it’s powered both by people and companies building software in the open for anyone to use or modify.  And that last sentence is important – if anyone can modify it or make it better, why wouldn’t I help if I have the time and / or the skills?

So I did.  Jumping back in with both feet.  After my wife gave me some feedback on the app I’m building that I needed to re-architect a large part of it, I took a break from it for the last week and wrote user help for two apps in GNOME: Polari, an IRC client, and Recipes, a brand new application that does exactly what you think it does.  I’m even poking around the documentation for Builder, an IDE for building GNOME apps, and editing its developer documentation.  (I won’t even pretend I know how to write developer documentation).  It’s a nice change of pace to use a different part of my brain to write user help while my subconscious figures out how I’m going to fix the data model in my app.

Having been away from the GNOME community for a number of years, I’ve always said the one thing I missed about open source was the people – and it’s been neat to be welcomed back and see some of the same faces.  I love the collaboration.  Maybe someday after I finish my Python webapp I’ll learn GTK and make myself a desktop app out of it.  But let’s not get ahead of myself.

GNOME Docs Team meeting tomorrow

What’s that? You follow planet.gnome.org but not news.gnome.org? For shame – we have a blog for the GNOME Documentation team but I guess this once I can cross-post for you.

We’re having a meeting tomorrow at 19:00 UTC in #docs on irc.gimp.org to start planning the topics and task for GNOME 3.0. We have big things (like GNOME Shell) to document and lots of little topics to tackle as we break up the old GNOME User Guide and organize it better.

As the post on the Docs blog says – now is a great time to get involved – even if you don’t know Docbook or Mallard, the important thing is to write the new user help and we’re here to help you learn.

See you there!

Quack – An update on GNOME 3.0 Help

One of the big improvements for GNOME 3.0 is new user help.  The Documentation Team is using Mallard to re-write the GNOME User Guide and a number of applications help files as well.

In GNOME today, most help files are written in a very linear structure by chapter using Docbook XML.  If you’re a user looking for help, it’s not always easy to find the right chapter that contains the topic you’re looking for help with.

Topic based help aims to fix that.  And to write topic based help, the GNOME Docs team will be using Mallard, a new XML language written by Shaun McCance aka the GNOME Documentation Project’s Fearless Leader.

The hardest part about writing good help (in any markup) is planning, planning, planning.  What feature might the user need help with? Where will they get stuck? How should the topics be organized?

From there, you write help that’s in the second person in a conversational tone to help the user.  (And choosing the right words is important as well to help the localization teams out, too).

Let’s use Tomboy’s help to compare.

Tomboy help in GNOME 2.30 using Docbook:

Tomboy 2.30 Help

Tomboy help re-written into topic based help for GNOME 3.0:

Tomboy Help for GNOME 3.0

Tomboy help re-written in Mallard

(And there are a number of topics you can’t see in the screenshot such as Common Problems, Advanced Actions and What’s New.)

The goal is to help users get to the help they need fast.  There’s always been a bit of an in-joke that users don’t read the help.  We’re aiming to change that.  When they need help, we need to present it quickly and easily.  (Which also ties in to the work Shaun is doing in Yelp 3.0).

For GNOME 3.0, we are going to re-write the GNOME User Guide.  This will be a difficult challenge due to the amount of information currently in the guide as well as GNOME Shell and the user interface being in development and we need for it to stabilize before writing the docs.  Shaun, Milo and Phil did a lot of planning around the user guide at the Desktop Help Summit this past April in Chicago.

In addition to this herculean task, a number of applications are in process of getting new help or replacing their old help with topic based help, including:

  • Banshee
  • Brasero
  • Cheese
  • F-Spot
  • gLabels
  • Rhythmbox
  • Tomboy

On a personal note, I finished Tomboy’s help and started Banshee’s help this weekend on the plane coming back from the Marketing hackfest.  I’d also like to thank Harold Schreckengost who just joined the docs team last month and has already started, if not finished, topic based help for Brasero and F-Spot.  (I committed the F-Spot help tonight on his behalf in a new branch – docs).

If you’re an application developer and you know of your help being written or re-written in Mallard, please add it to the list on the wiki.  App maintainers also may need to re-work the way help is called from the menu and help the doc writers review any new documentation for accuracy.  (Thanks in advance!)

If you’re a documentation writer, please visit the page above as well for examples on how we plan our writing for help and the Docs wiki has a lot of other great information for getting started too.  Take it from me, writing in Mallard is much easier than Docbook, and now is a great time to get involved with the Docs team and writing new user help as we’re all learning the new language and we can make a big impact on GNOME 3.0.

Plan your writing

I’ve been meaning to follow-up on Shaun’s recent bog post about “Explain More” when writing user help. Zonker’s blog post this morning on how to write an interview finally motivated me to get this blog post done.

One of my favorite sayings in a work environment is “Plan the work and work the plan”. This applies to writing as well.

One of the two major takeaways I had last year after attending the first Writing Open Source conference was the importance of planning. At least for me, almost of all the heavy lifting and hard work is done in the planning phase. (Not that writing and editing are easy either, but the planning for me is where my brain works the hardest).

When I was in school, especially high school, all of my English teachers required an outline when writing a term paper. School was fairly easy for me and I’d just write the paper and then do the outline. Oh, how I wish I had listened to them and learned those skills then!

It’s fascinating to me reading novels and then reading about or listening to an author talk about the years they spent researching their book. After last year, it’s finally clicked for me. (Having just finished io9‘s recent book club selection, The Windup Girl, by Paolo Bacigalupi I found his answers in the book club Q&A session fascinating, especially his research on Thailand and the Thai culture).

Planning your writing will help you connect with your readers, stay on message and help you faster. (Faster isn’t always better but you may spend less time getting stuck or if you do get stuck, be able to write the next section that you’ve planned and come back and finish where you were stuck).

Whether it’s user help, a blog post or an interview, spend some time thinking about what you want to write about and who your audience is. Your readers will thank you.

Banshee Documentation

I’ve been working on Banshee documentation on and off for the last few months (ok, more off than on) but as I get more comfortable writing in Mallard and the recent discussion in getting Banshee on the GNOME release cycle I am motivated to get this to done.

The most important part of writing documentation (or writing in general) is the planning phase. A few of us on the Docs team did a first pass at planning the topics that should be in the user help of Banshee in Google Wave, and I’ve copied that over to the GNOME wiki.

If you use Banshee, please give it a look – are there any topics missing that you think a user would want help with? Writing user help in Mallard gives us the ability to organize topics into groups – for a good example, check out the Empathy help. What’s missing? What would you organize differently?

Do you want to help? Have you written about Banshee features before? Let me know – either add content to the wiki page or post a link as a comment on my blog. If you have written a howto for Banshee, we’d love to include it – the new GNOME help is CC 3.0 licensed, so it’s easy to add from other sources, as long as it’s licensed as CC-SA 3.0. Please don’t feel you have to know how to write documentation or use Mallard – you can create a sub-page on the wiki for the topic and I will be more than happy to help edit it, convert it to Mallard and commit to git. Right now the important thing is to make sure we have the topics right and get some first drafts of the actual help created. I appreciate all help and would rather not do it all myself if at all possible!

There is a Banshee Docs branch on Gitorious – if you do know Mallard and want to help let me know and I’ll get you added to the team. If you don’t know Mallard, let’s start writing some howto’s in the wiki!