in Documentation, GNOME, Linux

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.

Leave a Reply