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),
-
- Old default icon set
-
- New default icon set
-
- adding some icons to text because “click the fifth icon” isn’t particularly user-friendly (especially for RTL folks),
-
- Button descriptions
-
- Button descriptions, now with icons
-
- 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.
It’s a shame the BROADWAY as a Gtk backend seems to be going away, you could imagine this would have great oppertunities for generating screenshots, using GIMP running there, in the browser somehow, and then cropping the image as a CI operation.
Too much “somehow” for my taste, plus seems also irrelevant to me whether there’s broadway or not, plus usually no cropping needed when taking screenshots with GNOME tools, so I guess I don’t get your point.
Clicking the open GIMP help issues, I made Anubis unhappy, which is the first time I’ve done that… still, definitely worth having Abubis :)