MoodleDocs talk:Moodle Docs reorganisation

Jump to: navigation, search

Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Moodle Docs reorganisation.

Namespaces or... separate wikis?

One really "silly" (or no) thought I had yesterday...

I think we are going to have some problems when using namespaces to separate versions, because all the "common bits" (templates, categories, images, user, talk...) need to be also moved to namespaces, and some of them, really, cannot be moved as far as already belong to one namespace (for example, templates).

So, thinking on this... I just began thinking if wouldn't be better, instead... to have complete new wikies for this. So, for example, we'll end having:

I know it is a completely different beast from what had been thought until now, but it has some great advantages:

  1. Each version is 100% autocontained. So work is completely isolated.
  2. Easy to create new versions (just duplicate DB and Filesystem structures)
  3. No conficts with templates/images/categories at all.
  4. Each Moodle "knows" what to call, without problems. Just set the X.Y prefix in the URL accordingly with its version.
  5. One process can be run daily, looking for pagename coincidences across DBs, in order to display information in the header of each page.

In the other side, it also has some drawbacks:

  1. One change in, say, the "en/2.0/Backup_FAQ" will need to be manually replicated to all the pages in other wikies if necessary (note that happens also in the original "by namespace split" alternative.
  2. Size. The server needed space will grow. No doubt about that.
  3. Surely other things I haven't been able to imagine. Please think!

So that is... just one alternative that seems to solve some of the conflicts that will happen with the namespaces way. Discuss, discuss!

Edited: Just to make things more complex in our minds... perhaps another alternative could be to have one "commons" wiki (current one) for all the pages not tidied with versions, and then the 2.0, 2.1... above for information susceptible to change. That way common stuff could be edited only once (about, help, releases info, FAQs...) and Developers/Teacher/Admin.. pages would had their place in the versioned wikis, for easier evolution.

Ciao :-) --Eloy Lafuente (stronk7) 14:38, 18 March 2011 (UTC)

Hi Eloy, seems your idea wasn't so silly ;-) Thanks a lot for it!
Regarding drawback 1. I think it's fine for Backup FAQ edits to only be done to the latest version of the page, as surely they will only apply to the latest version? (Thinking we surely must have heard all possible questions about 1.9 backup by now!) --Helen Foster 17:49, 13 May 2011 (WST)

How do maintainers of non-English wikis like this?

As I have expressed in the chat, I am a bit afraid of how this reorganization would be accepted by the maintainers of non-English wikis. --David Mudrak 09:06, 31 March 2011 (UTC)

As primary maintainer of French Moodle Docs (With Nicolas Martignoni), i can say that there's nearly nobody involved in the French documentation :-( People would like to find usefull pages, but don't want (or don't know how) to take time to improve documentation (And they're most used to Forums). I personnally won't make the move to dedicated spaces for different Moodle versions, as i'm today not able to add all what would be needed in 1 version ! It's for me undoable to have several versions of the documentation.
So, if the main english documentation is splitted by version, i don't really know how i could work. It's always possible to link from different english versions to 1 french page (in interlink block), but the opposit is not doable. --Séverin Terrier 14:52, 31 March 2011 (UTC)
David and Séverin, thanks for your comments. We must figure out a solution which, as far as possible, everyone is happy with before starting to reorganise the documentation. I have just completed a Moodle Docs review of all the language wikis to see where we are since Moodle Docs was first set up in January 2006. --Helen Foster 09:56, 1 April 2011 (UTC)
Everyone, please let us know what you think of the plan for documentation in different languages outlined in MoodleDocs:Moodle Docs reorganisation. --Helen Foster 17:59, 13 May 2011 (WST)
Séverin, regarding inter-language linking, as you know, it has never been desirable or even possible for different languages to have exactly the same number of pages. Inter-language links in the en wiki will need to be cleaned up for wikis which are archived or deleted. Perhaps we should just try and keep inter-language links for the most important pages only? --Helen Foster 17:59, 13 May 2011 (WST)

For the German MoodleDocs Wiki I can say the following: we started with a group of 3 people in fall 2008 to translate the docs wiki. We concentrated on teacher and student documentation which is more or less up to date for Moodle 1.9. As already said by the french maintainer, we cannot work on wikis for 2.0, 2.1, etc. I would be glad to have a usable documentation just for Moodle 2 in one wiki or namespace, and this will be still too much work for such a small group of translators. --Gisela Hillenbrand 07:31, 5 April 2011 (UTC)

If we are going for separate wikis (clone and update), not much will need to be changed from eg. Moodle 2.0 wiki to Moodle 2.1 wiki, in any language, anyway.

Perhaps another solution - have a Google Translate button in all our wiki pages, automatically? Not ideal, I know, but possibly helpful. --Tomaz Lasic 08:30, 7 April 2011 (UTC)

Contrib and Developer information

Contrib

Will contrib wiki pages be automatically copied if there is a version in the modules and plugin's database for that version? I anticipate that my Collapsed Topics format should work without modification for both Moodle 2.0 and 2.1. I also think that contrib developers should be encouraged to provide wiki pages beyond the standard readme.txt file with links to installation, customisation and maintenance screen casts.

Developer information

Whilst I agree that developer wiki information is about future versions, perhaps there should be more information about the technologies in each version and how they work so that when they are depreciated and resurrected or built upon in future versions you can understand how they work. The 'thinking' behind the thought processes that went into how a new piece of functionality was developed should be recorded to understand the code better when you wish to extend / fix a particular version. Is there a 'Javadoc' sort of thing that could be created / published for each version? I remember there being something but hard to find and navigate around the code if you do not appreciate the software architecture of Moodle. For that fact, are there artefacts like: Use Case, Collaboration, Communication, Class, State Transition diagrams? Is there an architectural map linking everything together?

So I believe that each version should have a 'release' developer wiki.

--Gareth Barnard 19:22, 13 May 2011 (WST)

The required changes in the Moodle code

We will have to add a information about the major and minor version (like "2.0" or "2.1" etc) into relevant moodle.git branches so that we can use that information to generate the link. I just want to point out that this version information is required not only for these links but is needed for the language pack installer, too (as since 2.0, lang packs are versioned, too) and in the future will be needed for the plugin manager to obtain valid list of available updates of plugins for the given version.

It looks reasonable to have that information declared in the main version.php, for example as

$versioninfo = array('major' => 2, 'minor' => 1);

or

$versionref = '2.1';

or so. --David Mudrak 20:57, 13 May 2011 (WST)