Moodle documentation: Documentation ideas

Moodle documentation: Documentation ideas

by Ray Lawrence -
Number of replies: 6

Hi,

Just in case you don't get to the end of this post wink, a quick question. What's the position with the Wiki? Ready to accept contributions from all comers or still being set up?

I have few ideas that, although they will require a little extra work now, should speed up the creation of documentation once things get under way.

  • Identify all of the elements in Moodle e.g. links, buttons, icons, drop down lists etc. (there arent too many variations) and produce a Wiki page with an official name for each (e.g. is that drop down list or drop down menu?). Specify the verb and nouns associated with each e.g. pick and item, select an option. The will help that create a common feel to the create documentation as contributors will be using the same terms. It should also make things easier for proof readers/editors too.
  • Identify and agree the approach for each section e.g. does it start with an overview?, What is the logical way to work through item being documented?. We can probably come up with a general structure (more detailed than the one I spotted when looking at the Wiki a day or so ago) Edit: just had another look, some further work seems to have been done. There will be exceptions to the rule that can be trashed out as they arise. The benefit of this method is that there is a common approach across the docs and a framework is created into which it should be easier for the hordes of contributors to slot in their contributions.
  • Impose which version of English is to be used less re-working later on and common feel throughout.
  • Agree the tense (I think this is the correct term for what follows, its a long time since I studied English) of the docs e.g. Click the button to display the xyz page or When the button is clicked the xyz page will be displayed. My preference is for the former, wherever possible.
  • Impose the theme which must be used for screen shots I know this has been discussed already, but things will be come a mess if contributors can use their own pet themes. Use of a variety of themes will be problematic for updating too IMO, especially the originator is not the one doing the updating.
  • Create a Contributors site with restricted access to those contributing (already mooted but I think it would be useful to have dedicated site). This site would be available for the following purposes:
    • Provide access to the Standard theme following on from my point above.
    • Create a haven where contributors can construct the scenarios required to investigate, acquire screen shots and document features within Moodle. These can be quite involved and need to be safe from disruption.

Average of ratings: -
In reply to Ray Lawrence

Re: Moodle documentation: Documentation ideas

by Przemyslaw Stencel -
Hi Ray,

You can find the wiki at http://docs.moodle.org - right now it's mostly the structure, but you can start adding content to it.

Now, regarding your suggestions above:

  1. re. unified terminology, version of English, tense - it would be great to agree on certain names for interface elements and on the use of particular verbs to denote interface actions. I guess the kind of document with preferred terminology could be a sub-page of the Guidelines for Contributors. The only thing that I'm worried about is: how much uniformity should we impose without the danger of losing casual contributors? If there are too many rules to follow when contributing, many people may give up. Just a thought for discussion smile
  2. re. the approach for each section - can you give a specific example of the kind of guidelines you're thinking of?
  3. re. contributors' site - I like this idea. At the moment the guidelines for contributors mention the teacher's playground as the place where contributor may experiment with Moodle. The problem is, it doesn't use the standard theme. Maybe we could direct people to test.moodle.com (if Martin agrees)? Or had we better set up a separate site just for documentation contributors? What do you think?
Average of ratings: -
In reply to Przemyslaw Stencel

Re: Moodle documentation: Documentation ideas

by Ray Lawrence -
1. Termnology: Yes, very much in the guidelines for contributors.

Casual contributors: Yes, possibly. Although it may also help casual conributors too. If casual (or regular conributors) additions do not take account of these then there will at least be firm guideleines for editors/proofreaders - if contributions are to be edited/proof-read/approved.

2. Yes. Bear with me I'll put something together.

3. Seperate for the reasons suggested IMO.
Average of ratings: -
In reply to Ray Lawrence

Re: Moodle documentation: Documentation ideas

by Ray Lawrence -
Ref. 2: I've not forgotten this.
Average of ratings: -
In reply to Ray Lawrence

Re: Moodle documentation: Documentation ideas

by Przemyslaw Stencel -
OK smile

In the meantime, if you have some spare time to help with the docs, send me your skype id - we'll talk about it.

Cheers,
Przemek
Average of ratings: -
In reply to Przemyslaw Stencel

Re: Moodle documentation: Documentation ideas

by N Hansen -
My experience in this sort of thing is that you can write all the guidelines you want, and you will be lucky if you get compliance half of the time. If you want a standard style or terminology, there is going to have to be editing done after the contributions are submitted. Some people will read the guidelines and follow them, others won't read them at all, others simply will read them and forget them, others will not understand them, and others will simply be too lazy to bother with trying to conform to them. In any case, I think guidelines are necessary, not only for contributors but as a reference guide for the editor. You should encourage people to follow them, but do let them know that they may be edited for conformity if they don't follow the guidelines, and then edit them as necessary.
Average of ratings: -