Documentation philosophy: Difference between revisions

Latest revision as of 13:42, 23 December 2013

Focus on Moodle Docs as the central Moodle 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 Moodle Docs
Encourage newcomers to contribute to Moodle Docs

"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 Moodle Docs by adding content in response to a question in the forums, then provide a link to the Moodle Docs page in the forum discussion
Provide "See also" links in Moodle Docs 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?==
+{{Help}}* Focus on '''Moodle Docs''' as the central Moodle 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 Moodle Docs
-* Additional documentation for
+* Encourage newcomers to contribute to Moodle Docs
-: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 Moodle Docs by adding content in response to a question in the forums, then provide a link to the Moodle Docs page in the forum discussion
-:Administrators
+* Provide "See also" links in Moodle Docs 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)
-:Developers
-==Documentation for every page in Moodle==
+[[Category:MoodleDocs]]
-* Every page in Moodle could have a help button in standard locations (in the header and footer).
-* The link this button contains would be automatically generated based on the page URL you are currently on: eg: https://docs.moodle.org/index.php/course/view - this "master" page will be in English.
-==Further ideas==
+[[es:MoodleDocs:Filosofía de la documentación]]
-* Each documentation page will have its versions in other languages. If a page in a language other than English does not have any content, it will either be pre-filled with the English content, or will contain a link to the English version.
+[[zh:文档的哲学]]
-* When a new version of Moodle comes out, all of the contents of the documentation will be copied to a new location, e.g. https://docs.moodle.org/1.6/, where we'll modify it to match the features of the new release.
-[[Category:MoodleDocs information]]