Hi,
I want to move this discussion between Tim Hunt and me to the public forum.
Tim wrote (http://docs.moodle.org/en/User_talk:Frank_Ralf#I.27m_not_convinced_by_your_recent_FAQ_pages):
I don't see the point in pages like PHP_FAQ and JavaScript_FAQ.
# We already had pages like PHP. Forking that page seems like a bad idea.
# Almost all the questions are not frequently asked. When you you every seen people ask these questions in the forums?
I think you have added some useful content. I just think it would be better to refactor it, rather than forcing it into an abuse of the FAQ concept.
My opinion:
Hi, Tim. I see your point about not forking pages but refactoring existing ones, but I think FAQ pages are a better entry point. Even the documentation main page http://docs.moodle.org/en/Main_Page states "Please help us expand our frequently asked questions - see Category:FAQ."
I only found the PHP page by using the search function, which I think should not be the primary way to find documentation. Regarding the PHP page I already thought of merging the two, but I would prefer keeping the FAQ page instead.
Regarding JavaScript, I think a question like the recent one about "How do I add some javascript calls to the footer" (http://moodle.org/mod/forum/discuss.php?d=114891 ) is well worth an entry in a FAQ.
Another example: The Audio FAQ page serves merely as a redirect to the comprehensive Audio in Moodle page, but I think more people will find it via the FAQ page.
What do others think about this issue?
Kind regards,
Frank
Hi,
Too many and too long seems to be a recent theme. FAQs are relatively new and I agree we should be discussing some specifics to help us make some general common sense guidelines.
I am a big fan of creating links to MoodleDocs from forums. I would suggest the same be true from within FAQs. My evolving rule, if I can not provide links to other parts of MoodleDocs in an FAQ, then I should ask myself, why not? Yes, sometimes I am lazy (or ignorant), but that is my current standard to provide pithy answers in an FAQ.
The number of entries for an FAQ is another issue. Unofficially, I would promote using our collective experience to prioritize them, the the most common questions being at the top of the list This would be a good first step. Then take the second step of deleting some entries at the bottom once contributors and watchers get adjusted. Usually people are pretty good at adding new entries at the bottom, which would be the "not prioritized" area.
The PHP comments, reminds me of Helen's note that the Installing Moodle page maybe too long. Each system has it's little things that must be done and as this page has matured, it grown and sprawled to be all things to all users. In my opinion, this particular page is an entry page to a big subject and we just woke up to its function.
The same thing sort of happened on the Teacher documentation page in June 2008. There was too much there. Some brave soul just about deleted everything (not me) and put in links similar to the style of Adminstration documentation. Then we put in a nav template on the right and put a link for newbie's right at the start which goes to Getting started for teachers, the old page. 36,000 views of the page since it was created. I suspect many teachers are happy.
Deciding what is important is the tough part on an entry page. I believe that FAQs are an entry page. My observation is that in MoodleDocs we have evolved to entry pages trying to be KISS with the verbage and heavy on the links.
Sorry to ramble. Great post and discussion between Ralph and Tim.
Too many and too long seems to be a recent theme. FAQs are relatively new and I agree we should be discussing some specifics to help us make some general common sense guidelines.
I am a big fan of creating links to MoodleDocs from forums. I would suggest the same be true from within FAQs. My evolving rule, if I can not provide links to other parts of MoodleDocs in an FAQ, then I should ask myself, why not? Yes, sometimes I am lazy (or ignorant), but that is my current standard to provide pithy answers in an FAQ.
The number of entries for an FAQ is another issue. Unofficially, I would promote using our collective experience to prioritize them, the the most common questions being at the top of the list This would be a good first step. Then take the second step of deleting some entries at the bottom once contributors and watchers get adjusted. Usually people are pretty good at adding new entries at the bottom, which would be the "not prioritized" area.
The PHP comments, reminds me of Helen's note that the Installing Moodle page maybe too long. Each system has it's little things that must be done and as this page has matured, it grown and sprawled to be all things to all users. In my opinion, this particular page is an entry page to a big subject and we just woke up to its function.
The same thing sort of happened on the Teacher documentation page in June 2008. There was too much there. Some brave soul just about deleted everything (not me) and put in links similar to the style of Adminstration documentation. Then we put in a nav template on the right and put a link for newbie's right at the start which goes to Getting started for teachers, the old page. 36,000 views of the page since it was created. I suspect many teachers are happy.
Deciding what is important is the tough part on an entry page. I believe that FAQs are an entry page. My observation is that in MoodleDocs we have evolved to entry pages trying to be KISS with the verbage and heavy on the links.
Sorry to ramble. Great post and discussion between Ralph and Tim.
Can I just clarify that I mainly wanted to raise a potential concern. I could well be wrong. Thanks Frank for moving the discussion here to get more discussion. I am happy to accept whatever the consensus is.
Just some more input regarding this topic:
http://docs.moodle.org/en/User_talk:Helen_Foster#Suggestion_that_is_probably_total_overkill
http://docs.moodle.org/en/User_talk:Helen_Foster#Suggestion_that_is_probably_total_overkill
And this tracker issue might also be related:
"Create a welcome template for new Moodle Docs contributors"
http://tracker.moodle.org/browse/MDLSITE-591
"Create a welcome template for new Moodle Docs contributors"
http://tracker.moodle.org/browse/MDLSITE-591
Frank, Tim and Chris, thanks for your comments about Moodle Docs FAQ pages.
I think that our initiative to increase the number of FAQs, and the promotion of FAQ pages (MDLSITE-474) has resulted in far fewer cases of the same sort of question being asked frequently, and hopefully lots of people easily finding the answer to their questions. A big thank you to everyone who has contributed to our Frequently Asked Questions.
I generally try to follow the 'wiki way' with Moodle Docs, and encourage all contributions. Content can always be tidied up/reorganised at a later date. Thus, I suggest that PHP FAQ and JavaScript FAQ remain as they are for now, and we consider reorganising them in future if the number of FAQ pages becomes too large.
Chris, I like your rule: "If I can not provide links to other parts of MoodleDocs in an FAQ, then I should ask myself, why not?" Long documentation pages are intimidating and difficult to read, so we should try and keep FAQ pages as short as possible by providing links to other pages and moving content to new FAQ pages whenever necessary.
I think that our initiative to increase the number of FAQs, and the promotion of FAQ pages (MDLSITE-474) has resulted in far fewer cases of the same sort of question being asked frequently, and hopefully lots of people easily finding the answer to their questions. A big thank you to everyone who has contributed to our Frequently Asked Questions.
I generally try to follow the 'wiki way' with Moodle Docs, and encourage all contributions. Content can always be tidied up/reorganised at a later date. Thus, I suggest that PHP FAQ and JavaScript FAQ remain as they are for now, and we consider reorganising them in future if the number of FAQ pages becomes too large.
Chris, I like your rule: "If I can not provide links to other parts of MoodleDocs in an FAQ, then I should ask myself, why not?" Long documentation pages are intimidating and difficult to read, so we should try and keep FAQ pages as short as possible by providing links to other pages and moving content to new FAQ pages whenever necessary.
Some observations (taken from prior discussions):
- If docs are broken up in sections then a FAQ can simply point to the pertinent section (i.e. the wiki version of a FAQ, since a FAQ is a doc, should arguably only present the collection of questions, not answers, which would appear in the substantive portion of the docs anyway)
- Having separate substance in FAQ vs Docs means that they can (and I think do) get out of sync.
- In some cases creation of FAQ saps energy that could be applied to docs
- Shouldn't we be putting more time into the docs and providing easy access to material in the docs, as opposed to creating another class of docs.
- As I noted in my argument for an active search, search results in docs can be appear inexplicable and are most often explained by the search engine keying largely on title, not substance.....
- And I continue to see people ask the same questions about php.ini, htaccess, upload size, moodle structure, etc, etc.
- The mark of any PHM should not be their responses in the fora, but their transformation of that effort into documentation, if indeed docs are to be considered an appropriate source for documentation.
Marc,
Nicely put.
I like the links to sections from an FAQ myself But I also have to be very careful when I am editing a section heading because the link can break in place I might not think of.
Keep the FAQ verbage short and sweet, some context so the reader knows why they are being dumped to Creating .htaccess files is a noble goal.
Slightly off topic: php.ini, htaccess, upload size and moodle structure. I (self taught and not encumbered by knowledge) have hacked the start of a shortened Installing Moodle entry page Installing Moodle/Install draft. Installing Moodle/Install draft#See also shows a list of draft pages created from stuff I decided to split out from the big page (these are sub pages not real pages yet). Lot more work to be done on these pages if it gains concept approval.
I will spare all of you the "mature pages are like my mature head" analogy. I have not figure out teenagers since I was one, so I like to let them age as they will
Chris
Nicely put.
I like the links to sections from an FAQ myself But I also have to be very careful when I am editing a section heading because the link can break in place I might not think of.
Keep the FAQ verbage short and sweet, some context so the reader knows why they are being dumped to Creating .htaccess files is a noble goal.
Slightly off topic: php.ini, htaccess, upload size and moodle structure. I (self taught and not encumbered by knowledge) have hacked the start of a shortened Installing Moodle entry page Installing Moodle/Install draft. Installing Moodle/Install draft#See also shows a list of draft pages created from stuff I decided to split out from the big page (these are sub pages not real pages yet). Lot more work to be done on these pages if it gains concept approval.
I will spare all of you the "mature pages are like my mature head" analogy. I have not figure out teenagers since I was one, so I like to let them age as they will
Chris
I like all the interest in the docs, but we need to make sure that while we need not be on the same page (that's a joke....) we should all try to be aware of what else is in the docs and how other docs try to address specific issues..... integrating with existing docs and avoiding redundancy, except perhaps where approach is more significant than content, is important so that docs don't become cul-de-sacs. And one of the items I am most concerned about in the docs, as I have repeatedly whined about, is the ability to easily find answers - yes, this was just another ploy for an active search from the forums (I have been told by a source I consider authoritative that though I may be partial to the Latin, forums is preferable to fora, so be it....) Frankly, I don't think FAQs (in the more traditional form) are the answer (one still has to search, whether for the FAQ or the substantive solution.....) Moodle changes so quickly that if everyone were to lend a hand with docs we would likely still fall behind.....
I know there is a decision faq and some other install pages that I am sure you have reviewed, Chris.... but I wanted to mention as I raised to Helen that I think we need a category for docs that are under development that is not the Development: category as that means something else.... that way we can develop docs without users being able to locate them if you will, by making any default search not include same.... then we can hack away at will, and whensomething looks like it is ready for prime time we can move it into production.....
I know there is a decision faq and some other install pages that I am sure you have reviewed, Chris.... but I wanted to mention as I raised to Helen that I think we need a category for docs that are under development that is not the Development: category as that means something else.... that way we can develop docs without users being able to locate them if you will, by making any default search not include same.... then we can hack away at will, and whensomething looks like it is ready for prime time we can move it into production.....
Only some unsorted thoughts I got while following this thread.
- I see FAQs as an intermediary step between the unorganised an scattered "documentation" which is provided in the forums towards "real", structured documentation.
- FAQs provide an unintrusive way to point to different but related parts of the existing documentation.
- FAQs used in the described manner do not provide verbose answers themself but link to the elaborate documentation. So I see them more as a kind of "annotated index" than "real" FAQs. (You could very well call that an "abuse of the FAQ concept"...)
- Is there a way to tell which part of the documentation needs refactoring? Mere page view statistics won't necessarily tell you that, but such a list might help to allocate resources where they are most needed.
Frank, regarding finding documentation which need refactoring, we have a several templates which automatically add pages to a category - see MoodleDocs:Templates for a list of commonly used ones. Certain special pages, such as Special:Longpages, can also be helpful.
Helen, thanks for the two links. They are really helpful.
Hi Frank,
To an extent, I agree. However, I think we could make the distinction clearer:
a) Forums - unstructured questions/answers/discussions. Possibly used to gain ideas and information;
b) FAQ - structured content to answer a specific operational need which might go across a number of forums/documents but which help the user. Content here could be gained from forums (some sort of page hit to identify the most popular items?);
c) Documentation - the 'encyclopedia' of moodle where each feature is described, parameters outlined and uses detailed.
I see this sort of discussion in other forums I've posted to and it comes back to clear differentiation of knowledge and mangement of same.
Cheers,
Paul
To an extent, I agree. However, I think we could make the distinction clearer:
a) Forums - unstructured questions/answers/discussions. Possibly used to gain ideas and information;
b) FAQ - structured content to answer a specific operational need which might go across a number of forums/documents but which help the user. Content here could be gained from forums (some sort of page hit to identify the most popular items?);
c) Documentation - the 'encyclopedia' of moodle where each feature is described, parameters outlined and uses detailed.
I see this sort of discussion in other forums I've posted to and it comes back to clear differentiation of knowledge and mangement of same.
Cheers,
Paul
Marc, regarding having documentation pages which are not included in the default Moodle Docs search, are you thinking we should have another namespace, such as 'Experimental'?
My bad... Yes, I was confusing categories with namespaces. The problem with Experimental, as with Development is that they already have existing connotations (connotations which as I have mentioned before can be somewhat confusing (for example, documentation for Developers vs documentation regarding Moodle Development. ) I chose to add experimental: to draft pages initially to suggest that the pages were not for public consumption, but my search at the time on experimental did not bring up existing pages with Experimental... So perhaps a namespace called DraftDocs...
Another benefit of an additional namespace, besides I think making it easier to add collections of pages (as opposed to having to potentially add, delete, redirect) and avoiding public hits on non-production docs, might be presented via RSS, making it easier to keep track of developing docs.
BTW, from http://docs.moodle.org/en/Special:Recentchanges using RSS FF feature results were a bit unexpected and could use documenting as well ;=}
See appended image....
Another benefit of an additional namespace, besides I think making it easier to add collections of pages (as opposed to having to potentially add, delete, redirect) and avoiding public hits on non-production docs, might be presented via RSS, making it easier to keep track of developing docs.
BTW, from http://docs.moodle.org/en/Special:Recentchanges using RSS FF feature results were a bit unexpected and could use documenting as well ;=}
See appended image....
Marc and Chris, thanks for your comments.
Personally I don't like providing links to sections within a page, since I find it disorientating to follow a link and end up in the middle of a page. Also, as Chris points out, if the section heading is edited then the link is broken. Instead, I write something like "Please see the advice on upgrading more than one version in Upgrading" and hope that additional help can be obtained by browsing other sections in the page.
I agree that the Moodle Docs search leaves a lot to be desired. Last Sunday at FOSDEM 09, Brion Vibber of MediaWiki talked about using Lucene to improve the MediaWiki search. Moodle Docs would need to be upgraded to version 1.13 to make use of it though. In the meantime, let's encourage people to use the Google-powered moodle.org search at the top right of every page.
Personally I don't like providing links to sections within a page, since I find it disorientating to follow a link and end up in the middle of a page. Also, as Chris points out, if the section heading is edited then the link is broken. Instead, I write something like "Please see the advice on upgrading more than one version in Upgrading" and hope that additional help can be obtained by browsing other sections in the page.
I agree that the Moodle Docs search leaves a lot to be desired. Last Sunday at FOSDEM 09, Brion Vibber of MediaWiki talked about using Lucene to improve the MediaWiki search. Moodle Docs would need to be upgraded to version 1.13 to make use of it though. In the meantime, let's encourage people to use the Google-powered moodle.org search at the top right of every page.
Hi Helen,
I agree with you but sometimes linking to sections within a page can't be helped. A recent example is the great Block Creating Course (http://docs.moodle.org/en/Development:Blocks) which I am in the process of doing some refactoring. This also includes correcting all the broken links like [Blocks_Howto#variable_title| $this->title] to something like that [Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title].
If this were Moodle and not MediaWiki it would be great to make a auto-linked glossary out of the Appendix A: block_base Reference (http://docs.moodle.org/en/Development:Blocks/Appendix_A) but as it is linking to the individual sections seems to be the only solution.
I agree with you but sometimes linking to sections within a page can't be helped. A recent example is the great Block Creating Course (http://docs.moodle.org/en/Development:Blocks) which I am in the process of doing some refactoring. This also includes correcting all the broken links like [Blocks_Howto#variable_title| $this->title] to something like that [Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title].
If this were Moodle and not MediaWiki it would be great to make a auto-linked glossary out of the Appendix A: block_base Reference (http://docs.moodle.org/en/Development:Blocks/Appendix_A) but as it is linking to the individual sections seems to be the only solution.
For me, I think it less beneficial to dump someone at the top of a doc and ask them to dig about to look for what they followed the link for.... that's really the purpose of an anchor. And while I appreciate that Helen may get stuck cleaning up a mess here or there, if one is going to twiddle the docs, then making sure the links work should be something that is expected.... I am sorry if my manual anchors are creating any trouble 
And, it is troublesome in the larger and off-topic sense if you will that Moodle.org uses a wiki other than that employed in Moodle, which requires not only for editors to learn multiple wikis markup etc, but also multiple signons......
And, it is troublesome in the larger and off-topic sense if you will that Moodle.org uses a wiki other than that employed in Moodle, which requires not only for editors to learn multiple wikis markup etc, but also multiple signons......
Just linking to a related discussion:
"Should Moodle.org forums have a FAQ section?"
http://moodle.org/mod/forum/discuss.php?d=90165
"Should Moodle.org forums have a FAQ section?"
http://moodle.org/mod/forum/discuss.php?d=90165