Skip to content

Documentation

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!

Google Wave

Almost two months ago, Nigel Tao posted on his blog offering Google Wave invites to the GNOME community. I commented and requested some invites for the Documentation Team, with Nigel graciously granting the request, and he asked for some feedback after using Wave for the last month and a half or so.

Some of the feedback that I shared with him, in no particular order:

  • We in the Docs team have used Wave to do document planning. (Before writing anything, the most important thing you can do is plan, plan plan). Wave has been really useful that each member of the team will edit the Wave with the topics for the help file we plan to write, and then use the reply feature in the Wave to add comments. Especially being a distributed team, with two of us in the US and 2 in Europe, it’s been helpful. A wiki page would work about the same, but the fact that you can have the main Wave used for the document and see the feedback and comments in-line is nice.
  • We really haven’t used Wave for real-time collaboration, with the exception of doing last month’s meeting minutes for our monthly team meeting. I do like Wave for a use case like that better than Gobby, especially with Wave’s ability to add bullets and formatting.
  • One nice thing about Wave when doing documentation planning was how easy it was to add the lead developer of an app we were doing the planning for. He was then able to review what we were planning, and add feedback and suggestions.
  • One of the challenges in using Wave at this point in time, is the limited number of people using it. I think as it expands and grows, the use cases and adoption will grow exponentially.
  • Other things I’ve used Wave for include some of the GNOME Marketing hackfest planning and projectmallard.org planning. It’s helpful, and as mentioned above, I prefer Wave over a wiki, especially when formatting text such as bullets.

One thing that took me a while to figure out, which I finally figured out with a suggestion from a friend via Twitter, was how to do public searches. I’m interested in buying a Droid phone, and I did a search for “Droid” waves which was pretty cool when the search results came back and I could see all the public Waves about Droid.

Is Wave an email killer? In my opinion, not yet, but it has potential. Wave, to me, has awesome potential for group communication, but I’m not sure I’d use it over email for one to one communication.

(And yes, I’m aware of the irony of using a “proprietary” tool to do open source work. It was a test, and I like doing stuff on the cutting edge, so no comments in the blog about this please).

Thanks again Nigel!

Mallard Documentation

Did anyone watch The Office last Thursday night? Early in the episode, Dwight gives Jim a wood duck with a walkie-talkie built-in so Dwight can spy on Jim.

Jim: Thanks for the duck

Dwight: It’s not a duck, it’s a mallard!

This had me chuckling thinking about Mallard documentation. For the record, mallards are a much more beautiful duck than wood ducks.

There’s been a lot going on in the world of GNOME documentation. Mallard has been getting a lot of buzz, in the #docs IRC channel, on Twitter and identi.ca, the mailing list and blogs. People have taken notice of the new Empathy documentation with its new layout and focus on topic based documentation.

Here’s just a few of the things going on:

  • We’ve expanded our monthly GNOME Docs meetings, and we’re practically meeting every other week now. We’ll be having a working session in our next meeting November 8th focused on what a new GNOME User Guide (Shaun hates calling it a User Guide!) will look like for GNOME 3.0. Shaun came back from the Boston Summit with lots of ideas and discussions around user help and the work we’ll need to do for GNOME 3.0.
  • Milo Casagrande, author of the new Empathy help, recently blogged about his experience in writing the Empathy help. He includes the process he went through, writing per page topics and also includes code samples. If you’re looking into getting involved in writing GNOME documentation, his blog is a must read.
  • For the GNOME 2.29 cycle, I’m committed to writing new Tomboy help in Mallard as well as adding help to Banshee for the first time. I’m starting with Tomboy as its help is a bit more basic than Banshee which has more advanced features. I’ve created a docs branch in Tomboy’s GNOME git and have been adding pages over the last week or two to get up to speed on Mallard. I have to say, writing docs in Mallard is ten times easier than Docbook. The XML markup just makes sense and is so much simpler than Docbook.
  • For Banshee, I have a git branch on Gitorious. I’ve checked out the code again after not working on it for a couple of months and have started working on it.
  • Nigel hooked some members of the Docs team up with Google Wave invites. It’s been interesting trying out Wave for collaboration for Docs writing. Not so much writing the actual documentation, but it’s been helpful for planning the pages, which is the most important part of any writing. With us half a world apart we haven’t really had a chance to use Wave for real time collaboration which I think it’s more suited for, but it’s been helpful. At this point a wiki would probably work just as well, but I do like the threaded view which makes it easier to see when changes or updates were made in Wave.
  • Shaun is off working feverishly on a new Yelp help browser for GNOME 3.0. Details are scarce at this point, but he seems excited.
  • We’ve also launched ProjectMallard.org. It’s our goal that the Mallard XML schema is used in more than just GNOME. It’s early in Mallard’s development so no big announcements, but it’s helpful to think about user help in FOSS on a greater scale. The webpage is just a place holder at this point, but we have plans to add information on what Mallard is, how to get started including code samples, tools, specifications, extensions and more.
  • We’re planning on having a GNOME Docs meetup in Chicago on November 9th prior to the marketing hackfest. Jim Campbell from XFCE might stop by but unfortunately Nixternal of KDE fame will be out of town.

Now is a great time to get involved with GNOME Documentation. Stop by on IRC in #docs on GimpNET or join the mailing list, we’d love to share what is going on with Mallard and how we are planning to make user help a better experience.

Gran Canaria Part II

I continue to have a great time here at the Gran Canaria Desktop Summit. I keep putting off blogging as I’m just overwhelmed with everything going through my head, and trying to make a succinct blog post has been a challenge.

One of the best parts, especially as it’s my first GUADEC, is how welcoming everyone is. I think I’ve had lunch or dinner with a different group of people every meal. (The meals here are pretty good, but the conversations are even better).

I had the opportunity Monday to give an update on Documentation in the GNOME 3.0 Status session. It’s a bit intimidating standing in a spotlight (literally) and talking for 3-5 minutes about everything we’re doing. (Yes, Shaun, I made sure to make a point you released Mallard after 4 long years, though I forgot to give Bastien credit for helping fix my laptop so I have Mallard working on it). I was very nervous – I really need to practice my public speaking skills, especially as I want to do more talks for Marketing later in the year on the upcoming GNOME 3.0 release.

I also met Thomas, who does a lot of work on GNOME PR here in Europe and Germany, including working in the Press Room here at Gran Canaria for the Desktop Summit, and he had some great ideas of how we can improve our marketing communications, and some fair challenges about how it’s been done in the past. I look forward to working on bringing some of those ideas to life.

Speaking of Marketing, yesterday I had the chance to talk about the work the Marketing team is doing before the Advisory Board. I thought it went pretty well, and it wouldn’t have happened without Claus’ work on the marketing campaign on the Marketing wiki. I had a great conversation with Andreas last night as well, and I’m glad we have the Art team’s support with some of the ideas we have. I’m happy that a few people have come up to me and volunteered to help out more with Marketing stuff. Definitely need to get that task list and release calendar ready! And please come to the Marketing BoF at 3:00 tomorrow to learn more, though I’m guessing a lot of people will be doing the local tour.

The only downside to going to the Advisory Board meeting was missing a couple of the sessions I really wanted to see late yesterday afternoon. I need to go track Aaron down and learn more about what’s new in Banshee!

I’ve also recruited a few more writers for GNOME Journal – don’t forget, if you have a cool app you want to talk about or demo, please come find me. I’d love to turn those into articles for GNOME Journal later in the year.

Docs Team Meetings

The Docs team is having two meetings in the next week – a community Q&A session tomorrow, and a project meeting this Sunday. More details on our shiny new blog at http://blogs.gnome.org/docs/2009/06/24/upcoming-documentation-june-meetings/ (Thanks Olav for adding us to news.gnome.org!)

Speaking of our shiny new blog, does anyone know how to add additional authors to a blog on blogs.gnome.org? I haven’t been able to figure it out and I’d like to add Shaun. Is it a setting that’s right under my nose and I just don’t see it? Thanks!

GNOME Docs Hackfest Part II

Day three of the Writing Open Source conference was our hackfest. I previously showed off Milo’s work in Part I, but it’s probably best to start at the beginning.

We started day three by applying some of what we had learned over the first two days. When writing, especially documentation, it is best to plan your work. This includes knowing your audience, their personas, and understanding their needs.

Lynda Chiotti, with help from Janet Swisher, led us through a brainstorming exercise. Using a mind mapping tool, we brainstormed what users want to do (and might need help with) when using their computer.

This was important for a few different reasons. For GNOME 3.0, we want to re-write the GNOME User Guide as topic based help using Mallard. Re-creating might be a better word, as we are going to switch licenses from the GFDL to CC-SA 3.0, and it’s probably easier to re-write it from scratch than to contact all the previous authors over the years to get permission. More importantly, we need to think like our users. How many times do we, as GNOME power users and developers, talk to ourselves, and not think like the average computer user? If this user needs help, does our documentation help them? Do they get frustrated and stop using GNOME or GNOME applications? We have a unique opportunity to use both our tools and the launch of GNOME 3.0 to radically improve our documentation and help our users.

After that, Phil, Milo, Shaun and I spent some time talking about how we could improve the GNOME Documentation Project. There were no sacred cows, and we’ve launched an effort to overhaul the docs team, including:

  • Adding simple tasks that new contributors can do and then build on (thanks Emma!)
  • Focusing the docs team on writers, editors, and translators. Each perform different, but similar roles, including crossover. We need to improve our tools for each team, and communication.
  • Holding more regular meetings, including a monthly project meeting, and weekly community sessions to encourage participation
  • Developing a roadmap of tasks we want to accomplish, including both the documentation itself and the tools
  • Understanding Shaun’s role as our fearless documentation project leader, and how we can help him to free him up and not having the team be blocked on any one person.
  • Make a significant effort to coordinate with downstream distributions, including meetings and communication, introducing Mallard, and better comments within documentation.

And that’s just the recap! Our wiki space is going through a revamp as we bring this to life, and there is a lot more to come.

Lastly, while Phil and Milo started hacking on Empathy docs using Mallard, I jumped into Bugzilla. Almost half of our open bugs in gnome-user-docs were touched (36 of 80), and of those 36, 23 were closed. Finally, 16 commits were made to update the current User Guide, including reviewing and patches from contributors. Fun fact (or embarrassing) – the oldest bug fixed was from July, 2006.

Overall, woscon was an amazing experience, and we all learned a lot. A few years from now, we’ll be able to look back and say: “We were there when this began”.

I think I speak for all of the GNOME Docs team members who were there, including Phil, Milo, and Shaun when I say we are sincerely thankful for the GNOME Foundation’s sponsorship of our travel to the Writing Open Source conference. This conference was the brain child of Emma Jane Hogbin, and we are very grateful for all the time and effort she put in to organizing and hosting woscon.