MoodleDocs:Moodle Docs reorganisation: Difference between revisions

Latest revision as of 15:09, 27 March 2013

Note: This page is for analysing and figuring out how best to reorganise Moodle Docs for 2.0 and beyond.

The plan for each new stable version of Moodle is to copy the existing wiki to a new wiki for the new version. The version number will be included in the URL e.g. for the English documentation https://docs.moodle.org/2.0/en/, https://docs.moodle.org/2.1/en/ ...

'Moodle Docs for this page' links at the bottom of each page in Moodle will link to the appropriate version of the documentation.

The documentation will have a big table of contents and will no longer be separated into teacher and administrator documentation.

Developer documentation will be kept in a separate non-version-specific wiki, as developer documentation is usually written about future versions of Moodle.

Documentation in different languages

There are currently Moodle Docs wikis in 28 different languages. The Moodle Docs review 2011 lists the number of pages and users for each wiki, plus information on recent changes.

Moodle Docs contributors, please consider which of the following options you think would be most appropriate for your language:

Existing wiki copied to a new wiki for the new version of Moodle (as for the English wiki)
Continuation with existing wiki and mixing documentation for new versions of Moodle with documentation for older versions
Archive of existing wiki and 'Moodle Docs for this page' linking to the English documentation
Deletion of existing wiki

The Moodle Docs overview will be updated to provide links to all wikis, with headings such as '1.9 legacy documentation (may include 2.x docs mixed in)', ' 2.0 documentation', '2.1 documentation', ...

For languages which choose to continue with the existing wiki, it will be moved to a new URL docs.moodle.org/1.9/xx/. 'Moodle Docs for this page' links in Moodle 2.0 and future versions will automatically redirect to the new URL.

For wikis with no recent activity in the last 60 days, unless volunteers come forwards, the existing wiki will be archived. The archived wiki will be moved to a new URL such as docs.moodle.org/old/xx/. A link to the archived wiki will be included in the Moodle Docs overview page, however 'Moodle Docs for this page' links will no longer redirect to the archived wiki. Instead there will be redirects to the en wiki.

For wikis with very few pages, wiki admins will be asked whether they would like the wiki to be deleted.

@@ Line 1: / Line 1: @@
-<p class="note">'''Note:''' This page is for analysing and figuring out how best to reorganise Moodle Docs for 2.0 and beyond. It is a work-in-progress. ''Comments and suggestions are welcome!'' Please use the [[{{TALKPAGENAME}}|page comments]] or the [http://moodle.org/mod/forum/view.php?id=5838 Moodle documentation forum].</p>
+'''Note:''' This page is for analysing and figuring out how best to reorganise Moodle Docs for 2.0 and beyond.
-The plan for new versions of Moodle is to have:
+The plan for each new stable version of Moodle is to copy the existing wiki to a new wiki for the new version. The version number will be included in the URL e.g. for the English documentation https://docs.moodle.org/2.0/en/, https://docs.moodle.org/2.1/en/ ...
-# A table of contents, such as [[2.0]]
-# A version [http://www.mediawiki.org/wiki/Help:Namespaces namespace]
+'Moodle Docs for this page' links at the bottom of each page in Moodle will link to the appropriate version of the documentation.
-==A version namespace==
+The documentation will have a big table of contents and will no longer be separated into teacher and administrator documentation.
-All documentation about Moodle 2.0 will be kept in a 2.0 namespace i.e. each page title and URL will contain '2.0' e.g. 2.0:Forum.
+Developer documentation will be kept in a separate non-version-specific wiki, as developer documentation is usually written about future versions of Moodle.
-The existing teacher and administrator documentation will be cloned (including page histories), updated, tidied up and moved into the 2.0 namespace. When 2.1 is released, the process will be repeated for a 2.1 namespace.
+==Documentation in different languages==
-# Create a 2.0 namespace as described in http://www.mediawiki.org/wiki/Manual:Using_custom_namespaces
+There are currently Moodle Docs wikis in 28 different languages. The [https://spreadsheets.google.com/ccc?key=0AmamVlPpCnn4dE1CVmZlemgtLWNxSjZ2cDB3TzQwb1E&hl=en&authkey=CLyez8UP#gid=0 Moodle Docs review 2011] lists the number of pages and users for each wiki, plus information on recent changes.
-# Use [[Special:Export]] to export pages from [[:Category:Administrator]] and [[:Category:Teacher]]
-# Amend titles in the XML file by searching for <title> and replacing with <title>2.0:
-# Use [[Special:Import]] to import the XML file and create the pages in the 2.0 namespace
-==Tidying up==
+''Moodle Docs contributors, please consider which of the following options you think would be most appropriate for your language:''
-* Amend links within pages - all 2.0 pages should contain links to other 2.0 pages
+# Existing wiki copied to a new wiki for the new version of Moodle (as for the English wiki)
-* Rename all pages which already had 2.0 in the title e.g. [[Backup 2.0]]
+# Continuation with existing wiki and mixing documentation for new versions of Moodle with documentation for older versions
-* Remove references to legacy versions which are no longer maintained, such as [[:Category:Moodle 1.6]] or move to obsolete namespace
+# Archive of existing wiki and 'Moodle Docs for this page' linking to the English documentation
-* So that the pages in a category can be sorted according to their actual name, rather than having them all listed under '2.0', create templates for adding pages to major categories e.g. https://docs.moodle.org/test/Template:CategoryAdministrator (so that 2.0:Forum would be listed under F instead of 2.0) then replace <code><nowiki>[[Category:Administrator]]</nowiki></code> with <code><nowiki>{{CategoryAdministrator}}</nowiki></code>
+# Deletion of existing wiki
-==More things to do==
+The [https://docs.moodle.org/overview/ Moodle Docs overview] will be updated to provide links to all wikis, with headings such as '1.9 legacy documentation (may include 2.x docs mixed in)', ' 2.0 documentation', '2.1 documentation', ...
-* Change 'Moodle Docs for this page' links within Moodle 2.0
+For languages which choose to continue with the existing wiki, it will be moved to a new URL docs.moodle.org/1.9/xx/. 'Moodle Docs for this page' links in Moodle 2.0 and future versions will automatically redirect to the new URL.
-* Go through every page in Moodle and ensure that the 'Moodle Docs for this page' link redirects to the correct documentation page
-* Ensure all new features and major improvements as listed in [[Moodle 2.0 release notes]] are well-explained
-* Completely rewrite [[Installing Moodle]]
-* Improve [[Upgrading to Moodle 2.0]]
-* Redesign [[Main Page]]
-* Create a custom search block to enable easy searching for pages in the 2.0 namespace
-==Things to think about==
+For wikis with no recent activity in the last 60 days, unless volunteers come forwards, the existing wiki will be archived. The archived wiki will be moved to a new URL such as docs.moodle.org/old/xx/. A link to the archived wiki will be included in the Moodle Docs overview page, however 'Moodle Docs for this page' links will no longer redirect to the archived wiki. Instead there will be redirects to the en wiki.
-* Would version namespaces in the developer documentation be worth having?
+For wikis with very few pages, wiki admins will be asked whether they would like the wiki to be deleted.
-* Should the existing teacher and administrator documentation be moved into a 1.9 namespace? The documentation [[About Moodle]] could remain in the main namespace.
-* Could any of the tidying up be automated or done more efficiently using phpMyAdmin? Or a search and replace of the XML file before importing?
+==See also==
-* Do we need a 2.0 category as well as a 2.0 namespace? Consider [[:Category:Developer]] and the list of [https://docs.moodle.org/en/index.php?title=Special%3AAllPages&from=&namespace=100 all pages in the Development namespace] - are they both necessary?
-* From Eloy: The header automatically can show you: “You are viewing 2.0 doc page, also available : 1.9...”
+* MDLSITE-1279 - META: Moodle Docs reorganisation
-* Should templates be included when exporting pages?
+* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=176065 Update on Moodle 2.0 Docs] forum discussion
-* Would it be helpful for pages in a particular namespace e.g. Development to be styled differently? See http://www.mediawiki.org/wiki/Help:Namespaces#Identifying_namespaces for CSS method.
-* Would anyone want version namespaces for Moodle Docs in other languages?