The MoodleDoc wiki has categories for teacher documentation, admin documentation, developer documentation. Should it not also have a category for student documentation?
I think that if a student is clicking on the nice "MoodleDocs for this page" link at the bottom of a page in Moodle then the student would expect to go to the student documentation page, not the teacher documentation page.
Moodle documentation: Student documentation in MoodleDoc wiki?
by Gustav W Delius -
Number of replies: 17
Hi Gustav,
You're absolutely right about student documentation. Please note that the MoodleDocs pages Student documentation and Category: Student already exist - they are just awaiting contributions. We also need to find a solution for linking student documentation to pages in Moodle. All suggestions welcome!
You're absolutely right about student documentation. Please note that the MoodleDocs pages Student documentation and Category: Student already exist - they are just awaiting contributions. We also need to find a solution for linking student documentation to pages in Moodle. All suggestions welcome!
Students and teachers look to some mod or block and see different interfaces and ways to use. Thay need different help and guides. But page in wiki for one mod is named by mod, and have now teacher's guide at more cases.
In what pages we will write student's guides?
In what pages we will write student's guides?
We could use the MediaWiki namespace mechanism for distinguishing between student and teacher pages. We simply have to reserve the namespace "Student" for student docs. So for example the page user/view would explain what a teacher can see and do on the user profile page and Student:user/view would explain what a student can see and do.
In reply to Gustav W Delius
Re: But how diffirintiate teacher's docs from student's?
by Martin Dougiamas -
I'm not sure they should be separated. It might be better for overall understanding if these things are on the same page.
In reply to Martin Dougiamas
Re: But how diffirintiate teacher's docs from student's?
by Gustav W Delius -
I think I agree with Martin. But then we have to write the pages in the documentation with that in mind, so that the student visiting it does not get confused. So we need a policy decision on this. I noticed in the MoodleDocs history that there has been some flip-flopping on the issue. Teacher and student documentation were originally combined and were then split by Przem.
In reply to Gustav W Delius
Re: But how diffirintiate teacher's docs from student's?
by Gustav W Delius -
I am in the process of writing documentation for mod/quiz/view and here the student view is quite dramatically different from the student view. I really like Martin's idea that student and teacher documentation should be on the same page because it is indeed important for the teacher to also be aware of what the student sees. I have therefore given the page two subsections, the first called 'Student view' and the second called 'Teacher view'.
I know that the argument on whether MoodleDocs should hold documentation for students as well as teachers has not been decided yet. Personally I lean towards the solution of making it a teacher resource but include explanations on what students can see and do, so that teachers can copy and paste the relevant information and reuse it in their own explanations tailored to their own students and their environment.
I know that the argument on whether MoodleDocs should hold documentation for students as well as teachers has not been decided yet. Personally I lean towards the solution of making it a teacher resource but include explanations on what students can see and do, so that teachers can copy and paste the relevant information and reuse it in their own explanations tailored to their own students and their environment.
In reply to Gustav W Delius
Re: But how diffirintiate teacher's docs from student's?
by koen roggemans -
In an ideal world (you know it doesn't exist, right?) the student shouldn't have to read documentation. The interface should be self explaining for them.
For teachers, I can live with the fact that moodle has become so full of advanced features and tweaks, it needs more documentation then only the context sensitive questionmarks (altough I am very glad they survived the move of the documentation to the wiki).
From that point of view, I'm not so sure it's necessary to create an extended student documentation in the wiki. It might be good enough to do al little more effort on the questionmarks and leave the button to the wiki out of the student pages (they should read their course, not the moodledocs
)
edit: just noticed I dropped litteraly in the middle of an already long ongoing discussion, that way doubleposting some ideas. Anyway, I'll leave it here, still supporting this opinion of my own after reading (finally) the whole discussion.
For teachers, I can live with the fact that moodle has become so full of advanced features and tweaks, it needs more documentation then only the context sensitive questionmarks (altough I am very glad they survived the move of the documentation to the wiki).
From that point of view, I'm not so sure it's necessary to create an extended student documentation in the wiki. It might be good enough to do al little more effort on the questionmarks and leave the button to the wiki out of the student pages (they should read their course, not the moodledocs
edit: just noticed I dropped litteraly in the middle of an already long ongoing discussion, that way doubleposting some ideas. Anyway, I'll leave it here, still supporting this opinion of my own after reading (finally) the whole discussion.
In reply to Martin Dougiamas
Re: But how diffirintiate teacher's docs from student's?
by Darren Smith -
I'm not sure I can go along with that as all of the documentation would then have to be re-written for it to be understandable by an 11 year old (or younger if we are to include our primary collegues).
Perhaps this would be a good thing for non-technical teachers but sometimes complex concepts need complex descriptions with complex words. I don't feel you can address teachers and students in the same document. They have different needs.
Darren
Perhaps this would be a good thing for non-technical teachers but sometimes complex concepts need complex descriptions with complex words. I don't feel you can address teachers and students in the same document. They have different needs.
Darren
I have to hold my hands up here and say that I've a bit of a thing about the whole concept of "Student Documentation".
To take a step back from Students for a moment, lets look at Teacher's documentation requirements.
Teachers need a resource that empowers them to create appropriate activities for their Students, choosing from the breadth of the tool set.
Each activity module has a host of options and Teachers can create quite different experiences for Students in a series of activities which use the same Moodle module. Consequently, Teachers need a complete appraisal of features (which they can then apply to promote the desired outcomes).
In addition, Teachers may present activities which are functionally similar in ways which are quite diverse in the context of a course.
Consequentially, IMO it is difficult (if not impossible) to create a cohesive set of Student documentation as Students will never see all of the underlying features for themselves. Furthermore, again IMO, Students are (or arguably, should be) more engaged by the activity itself than the tool employed e.g. if studying Shakespeare are we more interested in the words of the Bard or the nature of the binding of the book from which we read?
I suspect that the vast majority of Students will prefer and expect to learn how to participate in activities from their Teacher and will be unlikely to venture into the Docs Wiki. Those that do read/contribute to the Docs Wiki may fall into to camps;
If setting up a role play, for example, how many Teachers would expect to send their Students away to read about role plays generally or invite someone else to enter the classroom to explain it? Isn't it more likely that a Teacher who has the confidence to embark upon such an activity would have the confidence to explain the mechanics of the activity and also prefer to set it in context too?
Of course, in writing the above I have focussed on things from a "course perspective". However, I think there are parallels in other areas encountered by Students - here the Docs Wiki can empower site Admins, support staff as well as Teachers.
In summary, I feel the efforts are best aimed at the categories other than Student Documentation.
To take a step back from Students for a moment, lets look at Teacher's documentation requirements.
Teachers need a resource that empowers them to create appropriate activities for their Students, choosing from the breadth of the tool set.
Each activity module has a host of options and Teachers can create quite different experiences for Students in a series of activities which use the same Moodle module. Consequently, Teachers need a complete appraisal of features (which they can then apply to promote the desired outcomes).
In addition, Teachers may present activities which are functionally similar in ways which are quite diverse in the context of a course.
Consequentially, IMO it is difficult (if not impossible) to create a cohesive set of Student documentation as Students will never see all of the underlying features for themselves. Furthermore, again IMO, Students are (or arguably, should be) more engaged by the activity itself than the tool employed e.g. if studying Shakespeare are we more interested in the words of the Bard or the nature of the binding of the book from which we read?
I suspect that the vast majority of Students will prefer and expect to learn how to participate in activities from their Teacher and will be unlikely to venture into the Docs Wiki. Those that do read/contribute to the Docs Wiki may fall into to camps;
- Interested in Moodle - in which case their desire to learn more may be satisfied by reading the comprehensive Teacher Docs.
- Poorly supported by their Teacher(s) - they may find the Teacher Docs useful, but are unlikely to find documentation which exactly matches their own specific activities.
If setting up a role play, for example, how many Teachers would expect to send their Students away to read about role plays generally or invite someone else to enter the classroom to explain it? Isn't it more likely that a Teacher who has the confidence to embark upon such an activity would have the confidence to explain the mechanics of the activity and also prefer to set it in context too?
Of course, in writing the above I have focussed on things from a "course perspective". However, I think there are parallels in other areas encountered by Students - here the Docs Wiki can empower site Admins, support staff as well as Teachers.
In summary, I feel the efforts are best aimed at the categories other than Student Documentation.
In reply to Ray Lawrence
Re: But how diffirintiate teacher's docs from student's?
by Martin Dougiamas -
Yes, I think the documentation regarding students in MoodleDocs will be more to the order of "what the student can or can't do", which is really aimed at the Teacher, not the student. As such it should be included on the same page (and in many cases there won't even need to be separate stuff about what students can see).
I believe the internal context-sensitive documentation is good enough for the basic usage that most students need.
I believe the internal context-sensitive documentation is good enough for the basic usage that most students need.
In reply to Martin Dougiamas
Re: But how diffirintiate teacher's docs from student's?
by Gustav W Delius -
I am quite convinced by now that the "MoodleDocs for this page" link will indeed be most useful for teachers and admins. After reading what Martin and Ray have written I no longer believe that we need this link to the wiki for supporting students. Students should be supported by the built-in help files.
This however does not mean, that there is no place on MoodleDocs for student help pages. The MoodleDocs wiki can be a tool to allow the Moodle community to collaborate on writing better help pages for Moodle that can then be incorporated into the language packs. Currently only a select few have the ability to contribute to the student help files and I feel that unfortunately that shows.
So I would like to encourage anyone who finds that he could improve on a particular help file in the language packs to create a page on the MoodleDocs wiki with the same name and to put his or her improved version into it. Others in the community can then improve it further. And after a while the new improved version can replace the old version in the language pack.
If I don't hear objections to this idea I might add this suggestion to the MoodleDocs Guidelines for Contributors
This however does not mean, that there is no place on MoodleDocs for student help pages. The MoodleDocs wiki can be a tool to allow the Moodle community to collaborate on writing better help pages for Moodle that can then be incorporated into the language packs. Currently only a select few have the ability to contribute to the student help files and I feel that unfortunately that shows.
So I would like to encourage anyone who finds that he could improve on a particular help file in the language packs to create a page on the MoodleDocs wiki with the same name and to put his or her improved version into it. Others in the community can then improve it further. And after a while the new improved version can replace the old version in the language pack.
If I don't hear objections to this idea I might add this suggestion to the MoodleDocs Guidelines for Contributors
In reply to Gustav W Delius
Re: But how diffirintiate teacher's docs from student's?
by Martin Dougiamas -
Don't jump into this idea. I think this may need some careful thinking.
The context help is meant to consist of very concise descriptions of what each feature or option provides (woo hoo, three con-words in a sentence!).
The programmer writes these, and all translations in 70 languages need to be as close as possible to the original description. When the programmer extends the features, they create a NEW help file version to match that version of that feature.
We can't go willy-nilly replacing these files with new content, or everything will get out of synch. At this stage I would like to keep the context documentation separate from the more free-flowing MoodleDocs stuff. However, I'm not against, as I said earlier, putting a link in each help file to "more information on moodledocs" for that help file.
The context help is meant to consist of very concise descriptions of what each feature or option provides (woo hoo, three con-words in a sentence!).
The programmer writes these, and all translations in 70 languages need to be as close as possible to the original description. When the programmer extends the features, they create a NEW help file version to match that version of that feature.
We can't go willy-nilly replacing these files with new content, or everything will get out of synch. At this stage I would like to keep the context documentation separate from the more free-flowing MoodleDocs stuff. However, I'm not against, as I said earlier, putting a link in each help file to "more information on moodledocs" for that help file.
In reply to Martin Dougiamas
Re: But how diffirintiate teacher's docs from student's?
by Gustav W Delius -
I didn't advocate to go willy-nilly replacing the files in the language packs. I advocated going willy-nilly on the wiki making suggestions for new content for the help pages. These would of course only be integrated into the language files after careful consideration. This is the beauty of the MoodleDocs wiki: the community can go willy-nilly (you notice I like that word and will add it to my vocabulary) there and developers can still keep control of what actually goes into the language packs.
I think it is clear that Moodle would benefit from more and better context-sensitive help files. Programmers are not always the people most interested in writing end-user help files. So making use of the community makes sense here. Many teachers and admins out in the real world have a better knowledge of where students need frequent help in using Moodle than the programmer.
I think it is clear that Moodle would benefit from more and better context-sensitive help files. Programmers are not always the people most interested in writing end-user help files. So making use of the community makes sense here. Many teachers and admins out in the real world have a better knowledge of where students need frequent help in using Moodle than the programmer.
The context help is meant to consist of very concise descriptions of what each feature or option provides (woo hoo, three con-words in a sentence!).
Concise? What about this one for "Ask Good Questions"?:
Questions adapted from Paul, R. (1993). Critical Thinking: How To Prepare Students for a Rapidly Changing World: Foundation for Critical Thinking, Santa Rosa, CA.
Concise? What about this one for "Ask Good Questions"?:
Questions
A good way to help other people think about a subject is to ask them a question about it. Being asked a good question can really help us put information together, evaluate our existing ideas and create new ideas.
Asking questions that are specifically intended to help others learn is known as Socratic questioning, named after Socrates in Ancient Greece.
Socratic questions require you to listen very carefully to the other person to help you judge and phrase your question in a helpful, constructive, and hopefully non-confrontational way.
Here are some examples of such questions:
Questions of clarification
- What do you mean when you say ______?
- What is your main point?
- How does _____ relate to _____?
- Could you put that another way?
- Let me see if I understand you; do you mean _____ or _____?
- How does this relate to our problem/discussion/issue?
- Jane, can you summarize in your own words what Richard said? ... Richard, is this what you meant?
- Could you give me an example?
- Would _____ be a good example of that?
Questions that probe assumptions
- What are you assuming here?
- What is Jenny assuming?
- What could we assume instead?
- You seem to be assuming _____. Do I understand you correctly?
- All of your reasoning depends on the idea that _____. Why have you based your reasoning on _____ instead of _____?
- You seem to be assuming _____. How do you justify taking that for granted?
- Is that always the case? Why do you think the assumption holds here?
- Why would someone make that assumption?
Questions that probe reasons and evidence
- Could you explain your reasons to us?
- How does that apply to this case?
- Is there a reason to doubt that evidence?
- Who is in a position to know that is true?
- What would you say to someone who said that ____?
- Can someone else give evidence to support that view?
- By what reasoning did you come to that conclusion?
- How could we find out if that is true?
Questions about viewpoints or perspectives
- What are you implying by that?
- When you say _____, are you implying _____?
- But, if that happened, what else would happen as a result? Why?
- What effect would that have?
- Would that necessarily happen or only possibly/probably happen?
- What is an alternative?
- If _____ and _____ are the case, then what might also be true?
- If we say that ____ is ethical, how about _____?
Questions that probe implications and consequences
- How can we find out?
- What does this question assume?
- Would _____ ask this question differently?
- How could someone settle this question?
- Can we break this question down at all?
- Is this question clear? Do we understand it?
- Is this question easy or hard to answer? Why?
- Do we all agree that this is the question?
- To answer this question, what other questions must we answer first?
- How would _____ state the issue?
- Why is this issue important?
- Is this the most important question, or is there an underlying question?
- Can you see how this might relate to ________?
Questions adapted from Paul, R. (1993). Critical Thinking: How To Prepare Students for a Rapidly Changing World: Foundation for Critical Thinking, Santa Rosa, CA.
In reply to Gustav W Delius
Re: Moodle documentation: Student documentation in MoodleDoc wiki?
by N Hansen -
What will happen to the context help files in Moodle with these new documentation links? I am concerned too about overwhelming students with more information than they need, and the suitability of the one-size-fits-all documentation and my own site. I have already hacked the contextual help on my site to NOT show the link to all help files to students because so much of the help files is designed for teachers, not students. It makes no sense to show them everything if it isn't all relevant to them. Moreover, I have hacked certain modules on my site to work differently from the standard, the language files also might be different. In doing so, I have changed the help files accordingly. Are these links to the documentation from one's site going to be standard or will it be a feature that can be turned on and off without a hack?
In reply to N Hansen
Re: Moodle documentation: Student documentation in MoodleDoc wiki?
by Martin Dougiamas -
a) The internal contextual help will not be changed and will continue to be developed as part of the language packs. We may even add links to the external documentation from the internal context help. Note that in 1.6 the language packs are no longer all included within Moodle, so you only need to download what you need.
b) The external links to documentation are optional. Even if you have them on, the admin can choose a different "root" to go to. So if you don't like http://docs.moodle.org/ you can choose http://docs.mysite.com instead and run your own documentation. Two things being thought about are a) providing a downloadable copy of the current wiki for mirrors to use, and b) adding a warning to the external links explaining that the docs being used are not the official ones.
b) The external links to documentation are optional. Even if you have them on, the admin can choose a different "root" to go to. So if you don't like http://docs.moodle.org/ you can choose http://docs.mysite.com instead and run your own documentation. Two things being thought about are a) providing a downloadable copy of the current wiki for mirrors to use, and b) adding a warning to the external links explaining that the docs being used are not the official ones.
In reply to Martin Dougiamas
Re: Moodle documentation: Student documentation in MoodleDoc wiki?
by Gustav W Delius -
I am glad that help files are going to continue to be kept in CVS in the language packs. This makes it easier for people who have localised their help files to update their installations to new versions of Moodle because they can easily merge the changes to the language packs into their local versions.
The main advantage of the MoodleDocs wiki is that the whole Moodle community can collaborate on writing good documentation. I think that this will lead to very good help files. Whenever a help file on MoodleDocs is clearly better than the built-in help file in a language pack then the page from the wiki could be copied to the language pack. That way the existence of the MoodleDocs wiki will also benefit people who want to stick to their internal help.
The main advantage of the MoodleDocs wiki is that the whole Moodle community can collaborate on writing good documentation. I think that this will lead to very good help files. Whenever a help file on MoodleDocs is clearly better than the built-in help file in a language pack then the page from the wiki could be copied to the language pack. That way the existence of the MoodleDocs wiki will also benefit people who want to stick to their internal help.