Tom wrote me:
> 1) I really didn't find the wiki ready for the task. Maybe it is just
> me. I couldn't figure out how to detach files from pages, I made a
> mess. I do believe I could pull off (still) a fairly rudimentary wiki
> this week, using just snapitz shots (better than movies), but...
Wiki can be frustrating. I don't like the name-based linking ... it
means we're stuck with titles and it's all rather inflexible if you
ever want to rearrange things. Wiki is not good at structure.
My long titles aren't helping, they should probably be very short
clear concept phrases instead , like "creating a course",
"adding a web page" etc ...
I feel lost too on the best way forward for all this.
One thing I'm pretty sure of is let's not worry about graphics at first
... just text-only (but relatively complete) would be a good start.
> 2) As I schemed and planned and drew up outline structures, I was
> frustrated by the language issue. If I take all kinds of screen shots
> in English, how does that help everyone in translation? And how can my
> text instructions be easy translated?
>
> I spent a couple days looking on the web/sourceforge for software
> solutions for documentation and found all of them lacking. Plus, like
> you, I'd rather have Moodle keep it all.
Another thought I've had in the back of my mind is that "Using Moodle"
is in fact the most comprehensive database of documentation that we
have ... I'm hoping the new google-like search capabilities will increase
the usefulness of all that data.
> I don't know enough about multilanguage filters, how you create and
> translate help docs, or whether I should construct files using
> moodle/admin/lang.php?mode=compare (we'd also need unique and
> corresponding .jpgs for each language pack), so I basically groaned to a
> stop. Somewhere in the back of my mind, I wondered whether Jon's
> floating hint boxes were appropriate to the task.
Indeed - really this is back to improved context-sensitive help
(expending the yellow buttons) and there is a lot that could be done here.
But I still think we need task-based help that leads people from an
outside understanding to a grasp of how Moodle works in general.
Matt's manual seems to be pretty good at this ... we should probably
start with that ...
Ideas, Ideas? I notice the biggest proponents of Wikis have not
been interested enough in it so far to write anything in the Wiki ...
In reply to Martin Dougiamas
Re: Moodle documentation: Thinking about ways forward ...
by Mike Churchward -
Martin wrote:
> Wiki can be frustrating. I don't like the name-based linking ... it
> means we're stuck with titles and it's all rather inflexible if you
> ever want to rearrange things.
Keep in mind you can now turn off name based linking (CamelCase), and you can specify the page name with a separate linked title.
So if you entered '[Intro to Documentation|IntroPage]' in the wiki, you would see the text 'Intro to Documentation' linked instead of the page name. Then, you can turn off 'Print wiki name on every page' and specify your own heading in the page. That way, you can name the page anything you want and link to iy using any text you want.
What other features do you think would make this an easier tool to do the things you want? There may already be plugins available to do this.
mike
> Wiki can be frustrating. I don't like the name-based linking ... it
> means we're stuck with titles and it's all rather inflexible if you
> ever want to rearrange things.
Keep in mind you can now turn off name based linking (CamelCase), and you can specify the page name with a separate linked title.
So if you entered '[Intro to Documentation|IntroPage]' in the wiki, you would see the text 'Intro to Documentation' linked instead of the page name. Then, you can turn off 'Print wiki name on every page' and specify your own heading in the page. That way, you can name the page anything you want and link to iy using any text you want.
What other features do you think would make this an easier tool to do the things you want? There may already be plugins available to do this.
mike
In reply to Mike Churchward
Re: Moodle documentation: Thinking about ways forward ...
by Martin Dougiamas -
I didn't know that, Mike, thanks! I thought the link had to be the same as the name of the page.
That makes things easier!
Ok, so we should probably go for short page names then rather than these long ones.
Is there any way to rename a page via the GUI? Hacking the database is fine otherwise.
That makes things easier!
Is there any way to rename a page via the GUI? Hacking the database is fine otherwise.
In reply to Martin Dougiamas
Re: Moodle documentation: Thinking about ways forward ...
by Mike Churchward -
In its simplest case that's true. But the wiki standards (which aren't really standards) have evolved to allow people to create more complex linking if they're capable.
There isn't any way to do that via the interface now. That might be something useful. The risk is that it you would lose all existing links, but that seems to work with wiki philosophy. It might be nice to go through the wiki and update any existing links. I'll look into that.
mike
There isn't any way to do that via the interface now. That might be something useful. The risk is that it you would lose all existing links, but that seems to work with wiki philosophy. It might be nice to go through the wiki and update any existing links. I'll look into that.
mike
In reply to Martin Dougiamas
Re: Moodle documentation: Thinking about ways forward ...
by David Scotson -
Another thought I've had in the back of my mind is that "Using Moodle" is in fact the most comprehensive database of documentation that we have
A very true statement. There is an article (transcribed presentation) called Splitting Books Open: Trends in Traditional and Online Technical Documentation on O'Reilly's website exploring this issue. Though often written from the point of view of a publisher (and becoming something of an advert in the middle) I think it picks up on a lot of the trends that have made Using Moodle such an excellent resource.
You could probably distil some alternative 'documentation' guidelines from it, such as asking regular contributors to consider the wider audience (and Google) when answering tech questions.