A couple of months after I finished rewriting the Vinagre help in Mallard, I have had to come back to it because the user interface changed quite significantly (and will continue to change), so some of the help pages needed rewriting/removing/reordering. Dave also noticed that the online version of the help was rather old and Damned Lies showed more translations of the help than actually existed.
One bug and a fix later, the online version should always be up-to-date now. Damned Lies has also been updated (the bug was fixed very quickly by Claude Paroz) which was followed by a surge of translations! More are always welcome
I based my application for the Outreach Program on a DocBook to Mallard port of the Vinagre help.. suffice to say, it wasn’t that great. So, I have now fixed it up, with some pointers from Shaun, to be more topic-oriented and less *ahem* technical.
I have since started working on Brasero. This time, I have an advantage of starting with some notes for what should be included in the help, which were written up at the Open Help Conference brainstorming sprint. While writing instructions on how to use the application is not particularly challenging, I am finding that writing in a way which is “not technical” and understandable by users who would look at the help quite difficult, because terms which I take for granted are often misunderstood or not known by the audience I should be aiming at.. which is probably not anyone reading this blog. But the biggest problem I have come across is that Brasero could do with some love and care. I won’t count the number of ways of making it crash that I have managed to find, but with 229 open bugs, it is in need of some maintenance.
I have not been able to find a good guide on the style of the writing needed for user help, so I have been using the Empathy help as an example, with Shaun giving me feedback as I go along.