Documentation philosophy: Difference between revisions

Revision as of 14:58, 13 January 2006

Focus on MoodleDocs as a central knowledge-base
Transfer content from Using Moodle forum discussions (e.g. answers to how-to questions, ideas/suggestions of ways of using a particular feature) to MoodleDocs
Encourage newcomers to contribute to MoodleDocs

"New users are ideal for writing system-level documentation aimed at new users. They have the point of view and experience with the current software at the system level rather than at the library level. The most common evidence of this is FAQ lists, in which issues repeatedly raised on mailing lists and chat sessions are answered." Source: Documentation issues in open source

Encourage Using Moodle regulars to contribute to MoodleDocs by adding content in response to a question in the forums, then provide a link to the MoodleDocs page in the forum discussion e.g. Re: Backup problems forum discussion
Provide "See also" links in MoodleDocs to additional information in Using Moodle discussions e.g. Forums (though if the Using Moodle discussion leads to a conclusion/agreement then this should be transferred to MoodleDocs)

@@ Line 1: / Line 1: @@
-==What documentation is required?==
+* Focus on '''MoodleDocs''' as a central knowledge-base
-* Documentation for every page in Moodle
+* Transfer content from [http://moodle.org/course/view.php?id=5 Using Moodle] forum discussions (e.g. answers to how-to questions, ideas/suggestions of ways of using a particular feature) to MoodleDocs
-* Additional documentation for
+* Encourage newcomers to contribute to MoodleDocs
-:Students
+:"New users are ideal for writing system-level documentation aimed at new users. They have the point of view and experience with the current software at the system level rather than at the library level. The most common evidence of this is FAQ lists, in which issues repeatedly raised on mailing lists and chat sessions are answered." Source: [http://www.oss-watch.ac.uk/resources/documentation.xml Documentation issues in open source]
-:Teachers
+* Encourage Using Moodle regulars to contribute to MoodleDocs by adding content in response to a question in the forums, then provide a link to the MoodleDocs page in the forum discussion e.g. [http://moodle.org/mod/forum/discuss.php?d=35231&parent=163326 Re: Backup problems] forum discussion
-:Administrators
+* Provide "See also" links in MoodleDocs to additional information in Using Moodle discussions e.g. [[Mod/forum/index|Forums]] (though if the Using Moodle discussion leads to a conclusion/agreement then this should be transferred to MoodleDocs)
-:Developers
-==Documentation for every page in Moodle==
-* Moodle 1.6 will have a button in the header that links to pages in the wiki with the same path as the pages in Moodle e.g. https://docs.moodle.org/wiki/mod/forum/view/.
-* Other languages will have the two-letter language code added e.g. "de".
-* All help that refers to specific moodle pages/functions should be in this tree of pages.
-==Additional documentation==
-* Any other pages created should have short, single-word, lowercase URL names. The reason is to try and keep things generic enough to avoid breaking links later. If the titles are long with many words then we'll have to rename them sooner, which breaks links.
 [[Category:MoodleDocs]]