My name is Kristina and I like writing documentation.

That’s how I started my Pizza Thursday presentation at Catalyst today. And it’s true. With the right motivation and also good tools, it can be an enjoyable task. The tools I used for the Mahara user manual are:

• reStructured Text: text markup
• Shutter: Ubuntu screenshot software which allows you to edit your screenshot and place so called callouts onto it (numbers in circles that are incremented)
• Sphinx: documentation tool that compiles rST files in beautiful HTML, PDF, ePub etc. files
• Git: version control system to keep my text and images etc. safe – we use Gitorius to share the files with others
• Read the Docs: site that hosts Sphinx documentations
• Launchpad: tracking and working on translations as well as bug tracker and Q&A
• Piwik: Web analytics software

For the Mahara 1.6 manual I will use Gimp instead of Shutter for editing screenshots because Iñaki adapted a script that can make the callouts in there. That way translators can use the original Gimp files and just replace their screenshots and then re-arrange the callouts if necessary. You can read his notes and watch a short demo of how to create callouts in Gimp.

The translations of the manual will require us to move to our own server as Read the Docs cannot yet be used for translated Sphinx documentations. Furthermore, we had to adapt the Sphinx script to deal with screenshots that are in other languages.

I had asked Melissa, a member of the Mahara development team at Catalyst, to investigate this and see if she could get it to work. And she did. 🙂 I haven’t seen the result live yet as we are waiting for our server and also need translations and their images, but if you want to know what was actually all necessary to make it work, you can check out her blog post for the details.

Knowing that Pizza Thursday presentations should be short as we usually only have about 45 minutes for introductions of new staff members and then about 3 presentations, I opted for a PechaKucha presentation again. My last one was on Mahara 1.5 during our May Pizza Talks. This presentation format is a challenging one as you need to think very clearly – more so than for a presentation that can go longer I think – of what you want to say as you only have 20 seconds for each slide and you have to have 20 slides altogether.

Without further ado, here is my presentation including the recording so you actually know what I mean with my slides.

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.