Better help files

Better help files

by Ralf Hilgenstock -
Number of replies: 32
Core developers को तस्बिर Particularly helpful Moodlers को तस्बिर Translators को तस्बिर
From time to time I see help files that are very short, where I would like to see more or better information.

We had a discussion in the German translation team about the concept of translation work. There were two different argumententations:
  • translate the original english text only
  • take the english text as base and create an own text that is good for the readers.
What do you think about this?


Average of ratings: -
In reply to Ralf Hilgenstock

Re: Better help files

by Tim Hunt -
Core developers को तस्बिर Documentation writers को तस्बिर Particularly helpful Moodlers को तस्बिर Peer reviewers को तस्बिर Plugin developers को तस्बिर
How about option 3: Improve the English text then translate the improved content?
Average of ratings: -
In reply to Tim Hunt

Re: Better help files

by koen roggemans -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Plugin developers को तस्बिर Translators को तस्बिर
I second Tim's option 3.
What about suggestions for improving help files in the tracker?
BUT I think it is important to modify the text until good and then go under a different file name in the tracker, so it doesn't go in unnoticeable for translators. The original file could have a comment like <!--TRANSLATORS: this file is not used anymore after version 1.8-->
Average of ratings: -
In reply to koen roggemans

Re: Better help files

by Tim Hunt -
Core developers को तस्बिर Documentation writers को तस्बिर Particularly helpful Moodlers को तस्बिर Peer reviewers को तस्बिर Plugin developers को तस्बिर
Speaking as a developer, what would make my life easiest would be if the translation tools could be taught to connect to CVS (or maybe just look for a $Id: ...$ tag at the start of the file) and find out the last edited date on each file, and therefore automatically work out which help files changed when, and so which ones need updating.

But of course, that is just me, and there must be hundreds of translators, and only one of me.
Average of ratings: -
In reply to Tim Hunt

Re: Better help files

by David Mudrák -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Peer reviewers को तस्बिर Plugin developers को तस्बिर Plugins guardians को तस्बिर Testers को तस्बिर Translators को तस्बिर
Hi Tim,

I would love to have such feature as well (so, at least, we are two of the hundreds wink). The problem I can see is that we can't rely on $Id$ tag being present as a part of a file: AFAIK one can set up her CVS client not to include $Id$ and other keyword in the checkout.
But, of course, there is always a way how to automagically keep a modification timestamp in the help file. Let's discuss the best way thoughtful
Average of ratings: -
In reply to David Mudrák

Re: Better help files

by Tim Hunt -
Core developers को तस्बिर Documentation writers को तस्बिर Particularly helpful Moodlers को तस्बिर Peer reviewers को तस्बिर Plugin developers को तस्बिर
Well, the best thing would be to use the cvs log command, which produces output like this: http://moodle.cvs.sourceforge.net/moodle/moodle/lang/en_utf8/help/filters.html?view=log

Well, the command-line cvs obviously produces plain-text ouput, but that requires CVS installed on the computer you are on. If you would rather rely on a network connection, you can just use the generated HTML on sourceforge.net, and extract the information from there.

Anyway, it must be possible to script something, given enough effort.
Average of ratings: -
In reply to Tim Hunt

Re: Better help files

by koen roggemans -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Plugin developers को तस्बिर Translators को तस्बिर
For an improvement of a help file, I agree that a version system for the help files would be a good idea, and would make live easier both for translators and developers. But when features or procedures, where the help file is about, change, verioning it is not a good idea: too many translations run behind and changing the content of a help file without changing the name would make outdated or even wrong help files show up.
In that case, I think an English help file is better then an outdated or wrong one.
Average of ratings: -
In reply to koen roggemans

Re: Better help files

by Ralf Hilgenstock -
Core developers को तस्बिर Particularly helpful Moodlers को तस्बिर Translators को तस्बिर
Yes. Tims option is better than mine. I didn't suggest this because my own english isn't good enough to rewrite the english help files.

Koens idea to use the tracker is also good. If we do this, we create a versioning for help files. If we have changes in functionality we need this really.

There will be a cultural difference in several countries. We discussed this at an other point. German texts are mostly longer and more explaining than english texts.

I had the discussion about the help/ressourse/types/ims.html file yesterday.
The critics at the text was: Someone not knowing what IMS CP are doesnt understand more after reading the text. The linked information from IMS is also not very helpful.
A better text could have this parts:
- what is an IMS CP
- when is it senseful to use IMS CP
- what I need to create an IMS CP
- how to use an IMS CP in Moodle

This text would give someone never heard from IMS CP an information and he/she knows that IMS CP is not sensefull without an authoring system. This could be a helpful helpfile. But this files would be much longer than the existing file.

Average of ratings: -
In reply to Ralf Hilgenstock

Re: Better help files

by Helen Foster -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Plugin developers को तस्बिर Testers को तस्बिर Translators को तस्बिर
Hi Ralf,

I agree that some help files need improving, and that the issues should be reported in the tracker.

You're welcome to assign English help file improvement issues to me (or select Documentation as the component for it to be assigned to me automatically) and I'll rewrite the help files, renaming them if necessary. Please provide as much detail as possible regarding how the help file can be improved, as you've done for ims.html. (If you've not done so already, please add a report of this in the tracker.)

Regarding the length of help files, I think there needs to be a balance between providing sufficient information for the help file to be a help on its own, whilst making good use of the context-sensitive "Moodle Docs for this page" link to provide additional information and/or further explanation.

For example, regarding "what I need to create an IMS CP", a list of possible software could be added to the IMS CP page in Moodle Docs. The list can then be kept up-to-date/added to by any documentation contributor.
Average of ratings: -
In reply to Helen Foster

Re: Better help files

by David Mudrák -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Peer reviewers को तस्बिर Plugin developers को तस्बिर Plugins guardians को तस्बिर Testers को तस्बिर Translators को तस्बिर
Hi there,
the question is - do we really need to have these information in built-in help? Built-in help comes from pre-wiki ages. Wiki can solve a lot problems regarding help files and IMHO is a great solution of Ralf's issue.
Therefore, I suggest to keep help files as small as possible, probably with only a paragraph or so with a link do the wiki documentation. If you just need to explain something about a field in the form, the help is right place. If you want to explain how the whole module works, wiki fits better.
And as always when talking about the help and documentation, I add again: do not worry very much... They don't read it tongueout
Average of ratings: -
In reply to David Mudrák

Re: Better help files

by Séverin Terrier -
Documentation writers को तस्बिर Particularly helpful Moodlers को तस्बिर Testers को तस्बिर Translators को तस्बिर
I think the good choice would be Helen's one, keeping in mind not to make too long help files, and redirecting to the Wiki.

About the help files, i wouldn't only say that people don't read it (even if it's partially true), but also that most of the time (and not talking about Moodle), help files are useless ("select open to open..."), because they don't explain how things really work.
Average of ratings: -
In reply to Séverin Terrier

Re: Better help files

by Robert Brenstein -
Some help files are better than others. Some are indeed sort of pointless. Redirecting to wiki at moodle.org is fine for many things. However, what I am missing is a way, an option, to simply edit help files locally (in terms of user interface rather than digging directly into filesin order customize for local setup, local modes of usage, local people know-how...
Average of ratings: -
In reply to Robert Brenstein

Re: Better help files

by Ralf Hilgenstock -
Core developers को तस्बिर Particularly helpful Moodlers को तस्बिर Translators को तस्बिर
I have just called the German community to report the bloopers/bloomers in the help files.
Average of ratings: -
In reply to Robert Brenstein

Re: Better help files

by David Mudrák -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Peer reviewers को तस्बिर Plugin developers को तस्बिर Plugins guardians को तस्बिर Testers को तस्बिर Translators को तस्बिर
Hi Robert,
this is a quite wanted feature and I promised to implement it a long time ago. The current plan is to rewrite langdoc.php and merge it into the new lang.php interface. The new interface should allow modify help files in similar way as the string translation interface does at the moment.
Average of ratings: -
In reply to David Mudrák

Re: Better help files

by Ralf Hilgenstock -
Core developers को तस्बिर Particularly helpful Moodlers को तस्बिर Translators को तस्बिर
Hi David,

very small/short help files are great if the user has a lot of experience or prerequisites. But most user of help files doesn't have this knowledge.

Most of the help files are written by developers. Often they don't see what a simple user needs.

In the discussion with GUI and usability experts they have a lot of problems with Moodle structures.

Their priorities are:
  1. the GUI is self explaining
  2. the first help informations gives all the information needed
  3. only a few use the next information level, included in a link.
I will try it as example with the IMS help file and use the KISS principöe for texts. KEEP IT SHORT and SIMPLE.

Average of ratings: -
In reply to Ralf Hilgenstock

Re: Better help files

by Ralf Hilgenstock -
Core developers को तस्बिर Particularly helpful Moodlers को तस्बिर Translators को तस्बिर
Old text ressource/types/ims.html

IMS Content Packages

This resource type allows you add packages conforming to the IMS content packaging specifications to your course.

Simply upload a zipped package and deploy.

There are various options for displaying content in a popup window, with a navigation menu or buttons etc.


New text

Course Content from "IMS Content Packages"

Course content can also be edited by authoring software tools. You can add this zipped content as an IMS Content Package (IMS CP) in your Moodle course. The content is presented in several pages with navigation the students can walk through.

If you've edited content in your authoring system, you can export it as IMS CP. This creates a zip-file. Simply upload this file. Moodle unpacks this file and presents it to the students.

There are various options for displaying content in a popup window, with a navigation menu or buttons etc.

A list of authoring systems will be available soon at IMS content package information in Moodle documentation.





Average of ratings: -
In reply to Ralf Hilgenstock

Re: Better help files

by David Mudrák -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Peer reviewers को तस्बिर Plugin developers को तस्बिर Plugins guardians को तस्बिर Testers को तस्बिर Translators को तस्बिर
Yes, I like this style.
Average of ratings: -
In reply to David Mudrák

Re: Better help files

by Séverin Terrier -
Documentation writers को तस्बिर Particularly helpful Moodlers को तस्बिर Testers को तस्बिर Translators को तस्बिर
Yes, my +1 for this kind of help files smile

Just one information, when you say "Moodle unpacks" : is it made automagically on the fly when displaying the ressource, or will there be an unzip of the files, that will stay ?

I think this should be detailed, for the user to know if he should find (or not) uncompressed files.
Average of ratings: -
In reply to Ralf Hilgenstock

Re: Better help files

by David Mudrák -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Peer reviewers को तस्बिर Plugin developers को तस्बिर Plugins guardians को तस्बिर Testers को तस्बिर Translators को तस्बिर
Hi Ralf,

IMHO Moodle help files should not be texts where users can get experiences on how Moodle works. This is (and always was) the goal of documentation. I can imagine a help file as a one paragraph explaining what the field or button means/does followed by the link to a wiki page explaining more (probably whole form as a unit).
Sometimes, even experienced Moodler needs some help with e.g. quiz question syntax etc. This is something that should be included in a help file.
If we moved more and more information from help to wiki, a lot of other issues (how to improve help files, how to easily customize them etc.) would be sorted out.
Average of ratings: -
In reply to David Mudrák

Re: Better help files

by Helen Foster -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Plugin developers को तस्बिर Testers को तस्बिर Translators को तस्बिर
Just thinking about the usability issue regarding linking to the documentation wiki from a help file. I assume that the link would open in a new window? thoughtful

Would it not be better to encourage users to follow the "Moodle Docs for this page" link at the bottom of each page instead?
Average of ratings: -
In reply to Helen Foster

Re: Better help files

by Ray Lawrence -
+ 1 for the help files being limited to functionality rather than application and wider issues. The range of sectors in which moodle is used increases the likelihood of tips being added to the in build help files being redundant for many readers as they may not be relevant to their intended use of Moodle.

I'm also concerned that the help files become littered with links to various sites. Who is going to maintain/check the links on an ongoing basis? The usability/accessibility issue is a major one. At some point ion the future there needs to be a way of dealing with aspects of Moodle that currently use pop-up or new windows, adding links to the help files will not help this future refinement. Issue MDL-9851 provides a feel of some of the issues...

Moodle docs: Absolutely! This the ideal place for the community to do it's part in supplementing the in-build help files. Many benefits include: dynamic and editable content, shared effort i.e not dependant on those with CVS access, ability to add links, images etc.


Average of ratings: -
In reply to Helen Foster

Re: Better help files

by Ralf Hilgenstock -
Core developers को तस्बिर Particularly helpful Moodlers को तस्बिर Translators को तस्बिर
I'm thinking more about the wiki pages and have some questions.

Average of ratings: -
In reply to Ralf Hilgenstock

Re: Better help files

by Helen Foster -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Plugin developers को तस्बिर Testers को तस्बिर Translators को तस्बिर
Hi Ralf,

A list of pages linked from Moodle 1.6 can be found in Moodle Docs:Link pages. Many more pages are linked from Moodle 1.7 and 1.8. Obviously the easiest way to see which pages are linked from Moodle is to follow the "Moodle Docs for this page" links.

Regarding updating a translated wiki page, probably the easiest way is to follow the en inter-language link then check the page history.
Average of ratings: -
In reply to Helen Foster

Re: Better help files

by Ralf Hilgenstock -
Core developers को तस्बिर Particularly helpful Moodlers को तस्बिर Translators को तस्बिर
Hi Helen,

are there plans to update the Link pages?

For a translation team it is no good solution to check hundreds of pages about two steps to the page history to add updated pages.

Ralf

Average of ratings: -
In reply to Helen Foster

Re: Better help files

by Jeff Forssell -
I was interested in the inter-language links which I hadn't noticed before. (Hope my skimming of this thread hasn't missed something)

I tried looking up "Quiz"
and found links
In other languages
but if I went to Español
I just found:
Otros idiomas
Either the linking isn't working or it is manually done (or not) or it just goes between English and the other languages (which is, of course, better than nothing, but it would be good to know). If it has to be manually done than it would be good to know that (and how) if one makes a translation.

Average of ratings: -
In reply to Jeff Forssell

Re: Moodle Docs inter-language linking

by Helen Foster -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Plugin developers को तस्बिर Testers को तस्बिर Translators को तस्बिर
Hi Jeff,

Information on inter-language linking can be found in Moodle Docs Guidelines for contributors and Starting Moodle Docs in another language. If more explanation is needed, please say so.
Average of ratings: -
In reply to Helen Foster

Re: Moodle Docs inter-language linking

by Jeff Forssell -
I've just lost about an hours writing black eye, so I'm just checking that this is working.
Average of ratings: -
In reply to Helen Foster

Re: Moodle Docs inter-language linking

by Jeff Forssell -

Very Informative!

But the curse of Knowledge is that the multitude of questions grows with each answer!

Anyhow I decided to try to create a Swedish version of :

http://docs.moodle.org/en/MoodleDocs:Guidelines_for_contributors

I checked the way the other links were made to other languages (with translated names) and made a Swedish one. Viola, there was a new link and page!.

MoodleDocs:Riktlinjer för bidrag

Från MoodleDocs

(Det finns för tillfället ingen text på den härsidan.)

This page does not exist yet. You are welcome to create it or read the corresponding page in the English documentation .

I thought I would go back to the original page and copy the source and paste it in. I tried the link “which pages link here” which I thought would take me back to where I made the link that created the page, but “Inga sidor länkar hit.” (no pages link here)!!

I then tried the “corresponding page” link and came to:

MoodleDocs:Riktlinjer för bidrag

From MoodleDocs

This page does not exist yet. You are welcome to create it .

See also

I would expect the “corresponding” link to take me directly to the page (which shows up under "See also") rather than start creating a page with a foreign language name.

This passage:

Moodle Docs in a new language needs:

* An administrator (or two)

The administrator should understand MediaWiki features such as page redirects,categories, templates and disambiguation pages. Please browse this wiki to discover how these features work.

*Lots of people wishing to contribute

Please find out how many people are interested by discussing Moodle Docs in your moodle.org community discussion course.

Was enough to scare someone (like me) that is just trying to squeeze in some time to Wiki-document the things s/he learns while working with Moodle to save some others some sweat. Is there any way to do that without creating problems?

Another oddity I found was that if I checked the “upload” link in the Swedish wiki section and searched for “quiz” (or even Swedish for that: “test) I got zero hits. But it I tried on the English section I got about 30. For example:
http://docs.moodle.org/en/images_en/8/8f/Jmol-quiz-example.png
which is a picture that could be used in any language though it is embedded in an English page. It seems a waste to either recreate from scratch AND store or copy and restore on the (same) server.

Average of ratings: -
In reply to Jeff Forssell

Re: Moodle Docs inter-language linking

by koen roggemans -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Plugin developers को तस्बिर Translators को तस्बिर
What a post! I can't find in Svenska recent changes what you did. So I just shift to the last two paragraphs of your message.
When you do create a new page, make sure you have an inter language link to the English page. That way you don't create problems - the English page is still very accessible from your Svenka page for the time your page isn't ready yet. It is also nice to put an inter language link in the English page to bring your users back to the Svenska one.
You could also copy the English page in your Svenska Documentation and translate a little bit when you have time.

The images folder was initially the same for all languages, but is later on split up. It caused problems when people uploaded translated screenshots and saved them with the same filename as the original English one and thereby deleting it. So now every language has it's own images folder. Of course you can save an English screen shot and upload it in your language wiki, waiting for someone with more time to replace it with a localised one.
Don't feel intimidated to contribute: it's a wiki. If you make a mistake, anyone who notice it can and should correct it. Anyone who comes along can help you too.

Average of ratings: -
In reply to Ralf Hilgenstock

Re: Better help files

by Séverin Terrier -
Documentation writers को तस्बिर Particularly helpful Moodlers को तस्बिर Testers को तस्बिर Translators को तस्बिर
Hi,

trying to follow the french translation, i look each day (if possible, i always have a firefox tab open with it) to changed pages in the english last modification page : http://docs.moodle.org/en/Special:Recentchanges

Then, for pages that seems interesting, i look at the diff, and update the french version from that information...

If pages have multiple updates (or if i haven't seen one for a long time), i go to the page, then the history, and then i make the diff from the last time i updated the french version, to know what to update in the french version.

Sometimes i also put things in the french documentation, that aren't in the english one, if i think it's usefull smile

This branch of the thread would better be in the documentation forum wink
Average of ratings: -
In reply to Séverin Terrier

Re: Better help files

by koen roggemans -
Core developers को तस्बिर Documentation writers को तस्बिर Moodle HQ को तस्बिर Particularly helpful Moodlers को तस्बिर Plugin developers को तस्बिर Translators को तस्बिर
That's what translation/documentation needs the most: a (and preferably more then one) devoted person who tries to keep up with things. There is no technical solution to replace that.

May I suggest to keep modifications in the help files as low as possible. They are there as a reminder or as an initial, context sensitive help. If you want to read a lot, there are always the docs to read at the bottom of a page.

As for the documentation: since it is community build, the community gets the documentation it deserves. The more effort community members put in it, the better it will be. For not well maintained Moodle Docs, a lot is improved since the non-existing pages have an easy link to the English ones.
Average of ratings: -