03 November 2011, 16:02

I've just discovered the 'Mahara - User Guide' wiki, which looks like it could be a really great collaborative wiki where people could quickly get the resources they need to learn how to use Mahara: https://wiki.mahara.org/index.php/User_Guide 

However some of the content is partly in English and partly in another language:  https://wiki.mahara.org/index.php/User_Guide/1_Profile/2_Edit_profile_page

As these pages are a wiki they are easily edited, what is the 'ettiquette' about updating these pages and should there be an 'English version' as well as versions in other languages?

Also looks like a lot of the content pre v1.4 so it would be great to have a few people help update it for v1.4.

06 November 2011, 12:57

Hello Allison,

I am working on updating the Mahara user documentation so that we have an updated version for Mahara 1.4. Unfortunately, it takes me longer than expected. The new user documentation is written in AsciiDoc which will make it much easier also to print. Eventually, hopefully, there will be version in other languages, but I'll have to get done first...

Cheers

Kristina

08 November 2011, 4:56

The work you and your colleagues do for Mahara.org is fabulous Kristina. 

My comments weren't querying why Mahara.org hadn't updated the Mahara - User Guide wiki but more about how myself and others may be able to assist you with updating the Mahara-User Guide wiki to spread the workload.  I wanted to make sure it was ok to do this before just going ahead and doing it? 

I also wanted to know if it was OK to update the images which were non-English into English versions in the first instance?

08 November 2011, 13:32

Hello Allison,

Help is definitely appreciated. But as I said, we switched to a different way of doing the documentation which will hopefully be easier for translators eetc. to keep up and also to review the changes more easily and in a more structured way. dajan and I were going to chat about the documentation soon and that will also mean that we'll have to set up everything on the site. I am currently working on the first revised documents and finding my way around possible conventions, styling etc.

Hope to have something to show soon.

Cheers

Kristina

08 November 2011, 14:35

I understand about it taking longer than expected! We are rolling on to 1.4 as I speak, but when the technicians have finished in 90 minutes or so, I will still be working on the support manual. I tried portions of it on three audiences and found that potential new users wanted as many screen shots as possible, so have integrated a lot. I don't think my document is too complex, but it has taken ten times the hours I spent on any undergraduate essay. Today, it will be done and I will share a link to it.

08 November 2011, 23:36

Thank Gillian and Kristina.  I'm very much looking forward to the generous sharing of these resources.

09 November 2011, 0:37

Don't get too excited. I still haven't finished the guide... but I have put a couple of 4-5 sentence 'grabs' on a student forum to tide us over, and have just had feedback from a student that these are more helpful than a long guide. The guide should be ready tomorrow: it worked out to over 7mb so now I will break it down into connected topics. 

09 November 2011, 2:09

Hello Allison,

I uploaded the first pages of the documentation at http://mahara.org/view/view.php?id=49684 The nice thing about AsciiDoc is that the syntax is very easy and it generates a number of different files: not just html, but also PDF (I clearly still have to work on the image size there ;-) and DocBook.

I also want to link to existing resources online so that these are more integrated, esp. short screencasts.

The two first images are available as svg files so that translators (and others) can easily adapt them, e.g. in Inkscape.

Cheers

Kristina

15 November 2011, 17:06

Hello,

Francois found a better and as far as it looks like more widely used documentation system: Sphinx http://sphinx.pocoo.org/ . It has some nicer features and integrates well with http://readthedocs.org/

So I spent some time yesterday looking into it and like it. The syntax is similar to the Asciidoc one which meant that I didn't have to throw everything out, but mainly had to replace certain commands.

We pushed all the source files that already exist to https://gitorious.org/mahara/manual and Francois is looking into getting it up and running in Read the Docs. That means that as soon as I push new files to the documentation, they appear online and it will also be easy to keep track of different versions of the manual, e.g. 1.4 and then 1.5 once work starts on that.

Cheers

Kristina

18 November 2011, 2:13

Hello,

The Mahara 1.4 user documentation started to live at http://manual.mahara.org

Cheers

Kristina