GIMP user documentation

Posted on 2025-04-24 by aklapper

Over the last two years I’ve worked a bit in my spare time on the user documentation of GIMP, a Free & Open Source Image Editor.
While I personally still consider it pretty bad user documentation regarding style inconsistency, duplication of topics, “organic growth”, and lack of task orientation, I managed to put some lipstick on that pig across nearly 900 commits.
I was sometimes rather ruthless pushing my changes (plus I am only a simple contributor and not a GIMP developer) so I’d like to thank Jacob Boerema for their patience and lenience.

In particular that led to

  • pretty consistent and up-to-date user interface dialog screenshots using the default theme (a fun game in a repository with about 2000 images and no filename scheme whatsoever),
  • less trivial screenshots; people know how menus look like and all their entries are covered by accompanying text anyway (which created more work for translators),
  • all application icons updated to the default monochrome theme, in SVG format, located in one single directory within the docs repository, using the same filenames as in the GIMP code repository (so there’s theoretically a chance of maintenance),
  • adding some icons to text because “click the fifth icon” isn’t particularly user-friendly (especially for RTL folks),
  • slightly less quadruplication of string variants expressing the same meaning (which created more work for translators).

An interesting remaining issue is whether to remove outdated ancient localized screenshots and where to draw the line. Does having localized strings in the screenshot (not everybody prefers English) outweigh an outdated user interface in the screenshot (wrong numbers of buttons, or dropdowns instead of radio buttons)? Your mileage may vary.

Obviously there is much more to do, for example maybe rewriting everything from scratch or splitting screenshot files of translatable UI dialogs and non-translatable example images mashed into one single image file into two separate files because, again, translators and lower maintenance costs.

If you enjoy dealing with Docbook and all its quirks, see the open GIMP help issues or even write merge requests.

Posted in gnome, lang-en, user-documentation | 4 Comments

No more open tickets left in GNOME Bugzilla

Posted on 2021-07-10 by aklapper

It’s already been impossible for a while to create new tickets in GNOME Bugzilla when GNOME moved to GitLab for bug reports and feature requests (and many other software development aspects, of course).
In May 2021, Bart proposed to wrap up the Bugzilla migration (very appreciated). In addition, in November 2020 and May 2021 I (had) sent emails to maintainers (listed in the DOAP files in each Git repository) of all remaining code bases with open tickets left, with instructions to file a migration request for importing tickets from Bugzilla to GitLab if wanted.

Since this week there are finally no open tickets in GNOME Bugzilla left. All were either migrated to GNOME GitLab or mass-closed over the last weeks by Bart or me. When mass-closing, an explanatory comment was added (example) to allow contributors to understand why we closed their ticket.
While two or three authors expressed unhappiness about closing their more than 10 year old open tickets, most folks seem to be aware of the constraints of free and open source projects, aware of the need for infrastructure systems able to fulfil modern software development needs, or simply don’t care.
Creating new Bugzilla accounts has also been disabled, as (to my surprise) some folks are quite good in ignoring large banners on top of websites.

This brings GNOME closer to making its Bugzilla instance read-only, converting to static content, shutting down legacy systems that create maintenance costs.

Posted in bugzilla, computer, gnome, lang-en | 2 Comments

Creating tutorial videos (the hard way)

Posted on 2020-12-21 by aklapper

I recently created tutorial videos for Wikimedia Phabricator, the task tracking system primarily used in Wikimedia. These five tutorials cover the basics of creating tasks, working with projects and workboards, searching and listing tasks, and improving personal productivity. The videos are linked from the the central Wikimedia Phabricator help page and licensed under CC0.

Five videos on Wikimedia Commons

There are different types of technical documentation: Overviews for understanding, how-tos for problem solving, tutorials for learning, API references for information.
And there are different personal preferences how to learn (oral, verbal, physical, visual, etc).

While I’m content with Wikimedia’s written task-oriented documentation (“As a user, I want to know how to…”), it was missing an overview (“What is this? How is it supposed to be used?”) in a format easier to consume.

So I started to plan tutorial videos.

Which preparation and decisions does that require? I’m not going to list everything but here are some pointers:

  • Understand what you are getting into: Watch So you want to make videos? by Sarah Ley-Hamilton for how to approach. Or mistakes to avoid.
  • Install graphical video editing software; learn and understand the basics.
    • I initially played with Pitivi as a graphical video editing tool. While it is quite okay for my needs (and I’ve started to sometimes use it for video editing), at that time I wasn’t fully convinced due to occasional glitches and user interface issues hard to reproduce.
      I decided to give (non-graphical) ffmpeg a try. Which will only work out if you have raw video material which will not require to make exact sequence cuts on a specific millisecond. So you may want to use graphical video editing software instead. (Still, it was fun this way.)
  • Set up your system: Increase mouse pointer size, check how to visualize the pointer location (e.g. for mouse clicks)
  • Play with creating screencasts of browser content: Fullscreen vs window (the latter requires manually calculating the window’s width∶height to end up in 16∶9 after cropping, however while recording it allows you to see other open tabs to switch to), browser content zoom level, etc.
  • Sort out which information should be a screencast versus showing a static screenshot (intro and end slides, static webpages)
  • Plan what to cover. Write your script in a way that it can also be used as subtitles. Gather feedback (what’s missing or unclear?) and proofreading.
  • How much bling to have: Do I want to visually highlight areas, zoom in on videos, set up fade overlays between sequences?
  • Where and when to record audio without much background noise; is the microphone good enough?

The complete list of steps (setting up Phabricator locally, making customizations, creating test data, preparing the system, recording audio and video, cropping, merging, concatenating, exporting the final videos, creating subtitles, publishing everything) is publicly documented (html source).

Posted in computer, lang-en, phabricator, user-documentation, wikimedia | 2 Comments

Strike

Posted on 2020-11-11 by aklapper

Personal activity statistics on gitlab.gnome.org

✔ GNOME Gitlab achievement unlocked

✘ Write something about ‘life-work balance’ here

Posted in gnome, lang-en | 2 Comments

GNOME 3.36 user documentation updates

Posted on 2020-03-12 by aklapper

Looks like since the release of GNOME 3.34.0 in September 2019 I made exactly 500 commits in GNOME Git. :)

Localized screenshots shipped in GNOME 3.34 versus the same screenshot in 3.36

Localized screenshots shipped in GNOME 3.34 versus the same screenshot in 3.36

  • My main focus was on updating documentation. The user help of cheese, gnome-klotski, gnome-mahjongg, gnome-nibbles, gnome-robots, gnome-terminal, gnome-tetravex, iagno, lightsoff, quadrapassel, rhythmbox, zenity should be up-to-date in 3.36 again.
    (If not, then report issues in GNOME GitLab with the label “8. User Docs” or contribute patches yourself.)

  • This also included updating a majority of outdated screenshots (both English and localized versions when feasible) across projects.

  • I also took the liberty to push quite some trivial markup fixes in some translations when a language was not already reserved for translation on GNOME’s translation platform (as such actions would interfere).

Enjoy 3.36!

Posted in gnome, lang-en, user-documentation | 3 Comments

Prioritization of bug reports and feature requests in Free and Open Source software projects

Posted on 2019-07-08 by aklapper

A few months ago I wrote an essay on software development planning in FOSS projects. It tries to answer the following questions:

  • Why has nobody fixed this issue yet?
  • Why wasn’t I consulted about these changes?
  • How I can influence what is worked on?

Some parts of the essay are specific to Wikimedia but I hope it can also be useful for other communities. It is published under CC BY-SA 3.0 so feel free to remix.

If you have a similar document for your project, please feel free to share a link in the comments.

Posted in bugzilla, computer, gitlab, lang-en, phabricator, wikimedia | Comments Off on Prioritization of bug reports and feature requests in Free and Open Source software projects

Updating some GNOME 3.32 user documentation

Posted on 2019-03-28 by aklapper

Apart from replacing many broken links to git.gnome.org or replacing links to GNOME Bugzilla with links to GNOME Gitlab in many code repositories and wiki pages, in the last months I spent some good time updating random GNOME user docs all over the place:

Rhythmbox comparison

  • The user docs for Rhythmbox 3.4.3, GNOME Chess 3.32, five-or-more 3.32 and four-in-a-row 3.32 should be up-to-date.
  • The Totem 3.32 user documentation is up-to-date and now in Mallard format, based on work started in 2013 by Magda and Kat.
  • The screenshots in the user help of gnome-klotski, simple-scan, swell-foop, tali, and zenity are up-to-date.
  • Updated hopefully all places which mentioned an application menu now replaced by a menu button.
  • Removed a bunch of unused help images from some repositories shipped for no reason and bloating tarballs.

Enjoy and check the GNOME Wiki if you are interested in working on user documentation!

Posted in gnome, lang-en, user-documentation | 1 Comment

GNOME Bugzilla closed for new bug entry

Posted on 2019-03-20 by aklapper

As part of GNOME’s ongoing migration from Bugzilla to Gitlab, from today on there are no products left in GNOME Bugzilla which allow the creation of new tickets.
The ID of the last GNOME Bugzilla ticket is 797430 (note that there are gaps between 173191–200000 and 274555–299999 as the 2xxxxx ID range was used for tickets imported from Ximian Bugzilla).

Since the year 2000, the Bugzilla software had served as GNOME’s issue tracking system. As forges emerged which offer tight and convenient integration of issue tracking, code review of proposed patches, automated continuous integration testing, code repository browsing and hosting and further functionality, Bugzilla’s shortcomings became painful obstacles for modern software development practices.

Nearly all products which used GNOME Bugzilla have moved to GNOME Gitlab to manage issues. A few projects (Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy) have moved to other places (such as freedesktop.org Gitlab, self-hosted Bugzilla instances, or Github) to track their issues.

Reaching this milestone required finding, contacting and discussing over the last months with project maintainers of mostly less active projects which had used GNOME Bugzilla for their issue tracking.
For convenience, there are redirects in place (for those websites out there which still directly link to Bugzilla’s ticket creation page) to guide them to the new issue tracking venues.

Note that closing only refers to creating new tickets: There are still 189 products with 21019 open tickets in GNOME Bugzilla. IMO these tickets should either get migrated to Gitlab or mass-closed on a per-product basis, depending on maintainers’ preferences. The long-term goal should be making GNOME Bugzilla completely read-only.

I also fixed the custom “Browse” product pages in GNOME Bugzilla to get displayed (the previous code expected products to be open for new bug entry). Should make it easier again for maintainers to potentially triage and clean up their old open tickets in Bugzilla.

Thanks to Carlos and Andrea and everyone involved for all their help!

PS: Big Thanks to Lenka and everyone who signed the postcard for me at FOSDEM 2019. Missed you too! :)

Posted in bugzilla, gnome, lang-en | Comments Off on GNOME Bugzilla closed for new bug entry

Wikimedia in Google Code-in 2018

Posted on 2019-01-07 by aklapper
Newcomer and Mentor sticker designs

Newcomer and Mentor stickers designed by GCI 2017 participant Ashley Zhang, CC BY-SA 4.0.

Google Code-in (GCI) is an annual seven week long contest for 14–17-year-old students exploring free and open source software projects. Organizations, such as the Wikimedia community, offer small tasks in the areas of code, documentation, outreach, research, and design. Students who complete tasks receive a digital certificate and a shirt from Google. The top students in every participating organization win a visit of Google’s headquarters. Students can directly experience how large online projects are organized, collaborate with humans across the planet, and the students’ accepted work is made available to millions of worldwide users.

For the sixth time, Wikimedia was one of 27 participating organizations which offered tasks mentored by community members.

In late 2018, 199 students worked on 765 Wikimedia tasks with the help of 39 mentors. To list only some students’ achievements and show the variety of projects, areas, and programming languages in the Wikimedia community:

…and many many more.

Some students have also written about their experience. Google also posted a summary with statistics.

We would like to congratulate our winners Nathan and Shreyas Minocha, our finalists arcaynia, Jan Rosa, takidelfin and Zoran Dori, and all contributors on their many contributions! We hope to see you around! We would also like to thank all our mentors for their commitment to be available also on weekends and holidays, for coming up with task ideas, working together, quickly reviewing contributions, and for providing feedback what we could improve next time.
Thanks to everybody on IRC, Gerrit, Phabricator, mailing lists, Github, Telegram for their friendliness, patience, support and help.

Wikimedia always welcomes contributions to improve free and open knowledge. Find out how you can contribute.

Posted in lang-en, wikimedia | Comments Off on Wikimedia in Google Code-in 2018

Google Code-in 2018 and Wikimedia: Mentors and smaller tasks wanted!

Posted on 2018-09-13 by aklapper

Google Code-in will take place again soon (from October 23 to December 13). GCI is an annual contest for 13-17 year old students to start contributing to free and open projects. It is not only about coding: We also need tasks about design, documentation, outreach/research, and quality assurance. And you can mentor them!

Last year, 300 students worked on 760 Wikimedia tasks, supported by 51 mentors from our community.

  • Your gadget code uses some deprecated API calls?
  • You’d enjoy helping someone port your template to Lua?
  • You’d welcome some translation help (which cannot be performed by machines)?
  • Your documentation needs specific improvements?
  • Your user interface has some smaller design issues?
  • Your Outreachy/Summer of Code project welcomes small tweaks?
  • You have tasks in mind that welcome some research?

Note that “beginner tasks” (e.g. “Set up Vagrant”) and generic tasks are very welcome (like “Choose and fix 2 PHP7 issues from the list in this task” style).

If you have tasks in mind which would take an experienced contributor 2-3 hours, become a mentor and add your name to our list!

Thank you in advance, as we cannot run this without your help.

Posted in lang-en, wikimedia | Comments Off on Google Code-in 2018 and Wikimedia: Mentors and smaller tasks wanted!