I have just had an interesting discussion with Jeff Forssell who noticed that some of the built-in help pages could do with some improvements. Unfortunately currently there is no way for Moodle users to contribute to this process. Users can contribute to MoodleDocs and that is proving to be a great success. They can however no contribute to the built-in help pages.
My suggestion would be to put copies of all built-in help pages onto MoodleDocs and to automatically provide a link to this MoodleDocs page from the built-in help page. Users can then follow this link and improve the version on MoodleDocs. Whenever a MoodleDocs version has improved considerably over the old built-in version Helen can use it to update the built-in version in CVS and alert the translators so that the improvements can be translated into all languages. I think if we start this system with Moodle 1.6 then we will find that already Moodle 1.6.1 will have much improved help files. Users are likely to be much better at writing help files than developers.
It should be made clear that the built-in help pages should remain concise but I think they should be allowed to contain links to other relevant MoodleDocs pages with more detailed information.
Moodle documentation: Suggestion for improving built-in help pages
by Gustav W Delius -
Number of replies: 5
In reply to Gustav W Delius
Re: Moodle documentation: Suggestion for improving built-in help pages
by Martin Dougiamas -
I do appreciate this but ... won't we then be asking users to contribute to two completely separate but parallel sets of documentation? I can see some confusion there as well a lot more management.
There are some advantages to having developers control the context help files for features they write. I see them like "here's the developer's view" (which should be concise, and may contain information not be plainly obvious to users), and the Moodledocs link on the same page would be the "community view"...
If developers have trouble writing docs they can always ask for help before committing to CVS maybe?
There are some advantages to having developers control the context help files for features they write. I see them like "here's the developer's view" (which should be concise, and may contain information not be plainly obvious to users), and the Moodledocs link on the same page would be the "community view"...
If developers have trouble writing docs they can always ask for help before committing to CVS maybe?
In reply to Martin Dougiamas
Re: Moodle documentation: Suggestion for improving built-in help pages
by Gustav W Delius -
O.k., in that case perhaps when you ask people to do beta testing for Moodle 1.6 (after CVS is back) you could encourage testers explicitly to file bug reports also for any help file that needs improvement. Many developers (me included 
) will have forgotten that they still need to provide help for some of the new features.
I think the confusion between the built-in help files and the MoodleDocs pages already exists. One thing people might be tempted to do for example is to first click on the question mark icon to get help and then when they get to the bottom of that help page click on "MoodleDocs for this page" and expect to find a MoodleDocs page related to the content of the help page.
Should we make it general policy that a built-in help page should contain links to the relevant pages in MoodleDocs?
) will have forgotten that they still need to provide help for some of the new features.I think the confusion between the built-in help files and the MoodleDocs pages already exists. One thing people might be tempted to do for example is to first click on the question mark icon to get help and then when they get to the bottom of that help page click on "MoodleDocs for this page" and expect to find a MoodleDocs page related to the content of the help page.
Should we make it general policy that a built-in help page should contain links to the relevant pages in MoodleDocs?
In reply to Martin Dougiamas
Re: Moodle documentation: Suggestion for improving built-in help pages
by Chris Collman -
Hi Martin,
I asked Helen a similar question and she refered me to this post.
I guess I am not in complete agreement with you. Our common ground will be in the phrase "developers control the context help files for features they write".
I thought collaborations work because different people bring different skill sets to the task at hand. I am not trying to be mean.
Not all developers who write wonderful code amd design fantastic features, like to write clear, concise instructions. And, watching peoples actions tells me some developers put bug fixing and taking out the garbage on a higher list than re-writing help screens for the current version. These observations are not something unique to Moodle developers (bless them a 1000 times over).
It is true developers know things that are not plainly obvious to users, but it is equally true that developers often have blind spots of their own that essentially hides functionality from the user. Also, how often have we seen a feature used in a completely different way than was envisioned by the developer. This is part of Moodle and the education process. (sorry to be preaching to the choir)
The wonderful thing about MoodleDocs is that we have some great chief-editors that through collaboration of many writers are creating a certain consistant style and useful content for a wide range of user skill sets. The major drawback in Moodle help screens buttons is that they are not consistant. Further there is no consistant public forum to discuss them, nor how to share versions with the developer. MoodleDocs does this so well, why do we need to come up with another wheel?
I don't see why a developer can't use the content of a MoodleDoc version as the basis for "their/our" help screen. In fact, I would not link help buttons to a MoodleDoc for many reasons. I would also welcome some style guidelines for these help pages.
Why not figure out a MoodleDoc scheme like 1.6\ lang\en\help\lesson\overview. Even if a developer didn't want to use it, a Moodle administrator could grab it and replace a help file with a version of the collaborative effort.
Anyway, my opinions.
Thanks Chris
I asked Helen a similar question and she refered me to this post.
I guess I am not in complete agreement with you. Our common ground will be in the phrase "developers control the context help files for features they write".
I thought collaborations work because different people bring different skill sets to the task at hand. I am not trying to be mean.
Not all developers who write wonderful code amd design fantastic features, like to write clear, concise instructions. And, watching peoples actions tells me some developers put bug fixing and taking out the garbage on a higher list than re-writing help screens for the current version. These observations are not something unique to Moodle developers (bless them a 1000 times over).
It is true developers know things that are not plainly obvious to users, but it is equally true that developers often have blind spots of their own that essentially hides functionality from the user. Also, how often have we seen a feature used in a completely different way than was envisioned by the developer. This is part of Moodle and the education process. (sorry to be preaching to the choir)
The wonderful thing about MoodleDocs is that we have some great chief-editors that through collaboration of many writers are creating a certain consistant style and useful content for a wide range of user skill sets. The major drawback in Moodle help screens buttons is that they are not consistant. Further there is no consistant public forum to discuss them, nor how to share versions with the developer. MoodleDocs does this so well, why do we need to come up with another wheel?
I don't see why a developer can't use the content of a MoodleDoc version as the basis for "their/our" help screen. In fact, I would not link help buttons to a MoodleDoc for many reasons. I would also welcome some style guidelines for these help pages.
Why not figure out a MoodleDoc scheme like 1.6\ lang\en\help\lesson\overview. Even if a developer didn't want to use it, a Moodle administrator could grab it and replace a help file with a version of the collaborative effort.
Anyway, my opinions.
Thanks Chris
In reply to Chris Collman
Re: Moodle documentation: Suggestion for improving built-in help pages
by Mikey McLeod -
Can you tell me where the help files are located? The offical release version of Moodle may not want to change the help files, but as a course provider of a local installation of Moodle I would like to make them less concise and more helpful. Is there any issue with writing my own help files to replace the one's provided?
In reply to Mikey McLeod
Re: Moodle documentation: Suggestion for improving built-in help pages
by Helen Foster -
Hi Mikey,
Help files may be edited in the same way as language strings - either via Administration >> Configuration >> Language or directly e.g. in moodledata/lang/en. Please see docs.moodle.org/en/Language for further details.
Help files may be edited in the same way as language strings - either via Administration >> Configuration >> Language or directly e.g. in moodledata/lang/en. Please see docs.moodle.org/en/Language for further details.