Moodle documentation: "Non-Version" documentation pages

Moodle documentation: "Non-Version" documentation pages

by Guillermo Madero -
Number of replies: 20

Hi everyone,

Some time ago I added the Windows section to the Converting your MySQL database to UTF8 page related to Moodle 2.2. But now I see that that has to be done for the other three previous versions.

Taking in consideration that here we are only talking about database issues, from my point of view this kind of pages should be completely unrelated to a Moodle version.

Wouldn't it be best to have one page (e.g. docs.moodle.org/en/Converting_your_MySQL_database_to_UTF8) and then have the others redirect to this one?

If I were to expand a bit about some utf8 database conversion ideas, would it be right to put them in a Moodle version independent page and then just add a link to this page, or is it mandatory to have it added to each and every Moodle version page?

Average of ratings: Useful (1)
In reply to Guillermo Madero

Re: Moodle documentation: "Non-Version" documentation pages

by Mary Cooch -
Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Testers Picture of Translators

Hello there. I don't think it needs to be done for every Moodle version, just the current one and the one previous to it. So (for the moment!) that is Moodle 2.2 and 2.1. Very shortly (we hope!) documentation will be added to 2.3 and 2.2 (if relevant) Each time a version is upgraded the whole of the documentation is copied so if you have made changes in 2.2 for instance they will go into 2.3 straight away. I do understand what you mean about having non-version specific documentation -and I don't know the official answer, not being an official person but it seems to make sense to me to have separate pages for each version keeping them all as complete units. I don't know how you could actually make a "non-version specific" page anyway, as they are all either 1.9, 2.0 etc etc.

Anyway - if it is any help, I just copied and pasted your 2.2 Windows stuff into the 2.1 docswink

Average of ratings: -
In reply to Mary Cooch

Re: Moodle documentation: "Non-Version" documentation pages

by Guillermo Madero -

Hi Mary,

As some documentation pages don't have actually any Moodle related information, like the one I mentioned (which only has MySQL database info), I imagined that it could be set under a URL without a version number, for example, docs.moodle.org/en/Converting...(instead of docs.moodle.org/22/en/Converting...).

One would just need to update one page (leading to less maintenance work), and either make the normal ones redirect to the independent one, or add a link to them. This way normal pages would never become obsolete, as they would point to an always up-to-date page.

This is just a small proposal and maybe there aren't that many pages fitting this scheme, but I think this would improve a bit the structure of the documentation without disrupting it that much.

Thanks for you help! smile

Average of ratings: Useful (1)
In reply to Guillermo Madero

Re: Moodle documentation: "Non-Version" documentation pages

by Mary Cooch -
Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Testers Picture of Translators

Well; I don't know about the setting up of the documentation; that's Helen's job so we will see if she spots your post and has an opinionsmile

Average of ratings: Useful (1)
In reply to Guillermo Madero

Re: Moodle documentation: "Non-Version" documentation pages

by Dan Marsden -
Picture of Core developers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers Picture of Plugins guardians Picture of Testers Picture of Translators

Hi Guillermo - UTF8 issues are mainly for upgrading from 1.9 right? - Moodle 2.3 only allows upgrades from Moodle 2.2 so anyone with UTF8 issues should have resolved them as part of their 2.2 upgrades so it's probably not required in the 2.3 docs is it?

I have a SCORM page that I only maintain in one version of the docs here:
http://docs.moodle.org/22/en/Creating_SCORM_Content

When 2.3 is released I'll be copying the content from one of the old versions into the Moodle 2.2 version and the 2.3 version will contain the information like this(but usually Helen beats me to it anyway!)
http://docs.moodle.org/21/en/Creating_SCORM_Content

The other option for non-version docs pages is the dev wiki - some pages can be moved there although I'm not sure the one you point to here would sit in the dev docs - Helen is usually good at filtering what should go where so I'm sure she'll give pointers!

Average of ratings: -
In reply to Dan Marsden

Re: Moodle documentation: "Non-Version" documentation pages

by Guillermo Madero -

Hi Dan,

You are right about the steps, the utf8 info wouldn't actually be needed for the 2.3 page. However, as one can land at any particular version page when looking for some info, the copy/paste process will never die tongueout

This idea began because I wanted to take some pointers I've given in some posts and add them to the ut8 related page. And well, I thought it would be better to deal with just one independent page.

Recently I participated in a thread about the 2.x file system, and well, I was also thinking of making a page to delve a little more into this topic.

I worked as a system developer for many years, and because of this background I sometimes wished there were more technical explanations about how some things work (or why they work the way they do). Eventhough I know that for many users technical explanations aren't actually useful, for many others they will be like gold, as they will be able to actually understand what is really going on behind curtains, and thus, they will also be able to more easily help others solve their particular problems. I'd really look forward for some improvements in this area. Mhh, what about having weekly or biweekly live Q&A sessions with the developers?

Yes, as you mention, something like the "dev" pages, maybe a "ref" or a "tech" section? Food for thought smile

Average of ratings: Useful (1)
In reply to Guillermo Madero

Re: Moodle documentation: "Non-Version" documentation pages

by Derek Chirnside -

Go for it Guillermo.

http://docs.moodle.org/dev/Reference

This is a wiki after all.

Best wishes,

-Derek

Average of ratings: Useful (1)
In reply to Derek Chirnside

Re: Moodle documentation: "Non-Version" documentation pages

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi Derek

You wrote:
> http://docs.moodle.org/dev/Reference
>
> This is a wiki after all.

Wait, I believe http://docs.moodle.org/dev/ is the wiki, http://docs.moodle.org/dev/Reference is "the start of a few pages of largely version independent reference", i.e. a _page_ in a wiki. Or am I mistaken?

Either way, if it grows with "version independent references" which are not necessarily developer information, what about the /dev/ prefix in the URL? Hopefully it stands for "developer", as dramatically demonstrated by one shy CEO. wink

Average of ratings: -
In reply to Visvanath Ratnaweera

Re: Moodle documentation: "Non-Version" documentation pages

by Derek Chirnside -

Smiling here.

At last count there were over 1000 pages in the dev wiki.  If we make a mistake Helen will just clean up our mess.  So I'm not really worried about the dev prefix.

-Derek

Average of ratings: Useful (1)
In reply to Visvanath Ratnaweera

Re: Moodle documentation: "Non-Version" documentation pages

by Guillermo Madero -

Hello Visvanath,

I agree about the "dev" URL, it refers to the quite specific developer section. My idea was to have a "ref" URL, just to have pages explaining issues outside Moodle and that wouldn't need to be cloned with each release. Anyway, I think it is a good start.

Average of ratings: -
In reply to Derek Chirnside

Re: Moodle documentation: "Non-Version" documentation pages

by Guillermo Madero -

Hi Derek,

Excellent! As you mention in your post, if something goes wrong, Helen will definitely come to our rescue smile

Average of ratings: -
In reply to Guillermo Madero

Re: Moodle documentation: "Non-Version" documentation pages

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi Guillermo

You wrote:
> the utf8 info wouldn't actually be needed for the 2.3 page.

If I'm not mistaken, utf8 story goes back to Moodle 1.6, and has influenced the upgrading process. For example, the confusion in this sub-thread http://moodle.org/mod/forum/discuss.php?d=197602#p890307 is indirectly related to utf8.

> ... something like the "dev" pages, ...

That is happening already, see http://docs.moodle.org/dev/Install_Moodle_On_Ubuntu_with_Nginx/PHP-fpm.

This could be the (only) workaround for my problem with http://docs.moodle.org/en/Installing_Moodle_on_Debian_based_distributions (valid for Moodle 1.6 through 2.3), which right now exists only in the /22/ wiki. See the discussion "How to subscribe to multiple categories" http://moodle.org/mod/forum/discuss.php?d=200288 for details.

The fact is that a series of indiscriminate decisions taken by the Moodle Docs planners have made the multiplying doc trees /19/ .. /23/ unmaintainable. You can see their effect all along this forum. I tried to summarize the worst two here: http://moodle.org/mod/forum/discuss.php?d=203002&parent=891634.

Good luck!
Average of ratings: Useful (2)
In reply to Visvanath Ratnaweera

Re: Moodle documentation: "Non-Version" documentation pages

by Frank Ralf -
To add to the confusion and give another example of the sorry state of Moodle Docs since the starting of the cloning.

I once created
http://docs.moodle.org/19/en/UTF-8_and_BOM

which got cloned as
http://docs.moodle.org/20/en/UTF-8_and_BOM
http://docs.moodle.org/21/en/UTF-8_and_BOM
http://docs.moodle.org/22/en/UTF-8_and_BOM
http://docs.moodle.org/23/en/UTF-8_and_BOM

Then someone created
http://docs.moodle.org/22/en/UTF-8_and_BOM:
(mind the colon which shouldn't be part of a wiki page title in the first place as it usually denotes a wiki namespace)

which will live on as
http://docs.moodle.org/23/en/UTF-8_and_BOM:

but isn't available as
http://docs.moodle.org/19/en/UTF-8_and_BOM:
http://docs.moodle.org/20/en/UTF-8_and_BOM:
http://docs.moodle.org/21/en/UTF-8_and_BOM:

And to round things up there is the non existing
http://docs.moodle.org/dev/UTF-8_and_BOM

So the current state is eleven (!) pages for one and the same topic.

I refrain from any further comment.
Frank

EDIT:
And to add insult to injury: Try searching any of the wikis for "BOM" and you won't find my article, not even in the Moodle 1.9 Docs!

This is plain crazy.



Average of ratings: -
In reply to Frank Ralf

Re: Moodle documentation: "Non-Version" documentation pages

by Guillermo Madero -

Hi Frank,

Plain crazy indeed. Wow! black eye

We really need to vote for a "ref" URL and make all those cloned pages (as well as many others) redirect to a new, specific, independent one Yes

Average of ratings: -
In reply to Guillermo Madero

Re: Moodle documentation: "Non-Version" documentation pages

by Helen Foster -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers Picture of Translators

Hi,

As Dan explains, there are two options for having just one version of a documentation page:

  • Redirecting to a page in the most recent version wiki from earlier version wikis
  • Including the page in the dev docs wiki

I think we have enough wikis with all the version ones and the dev docs, without creating yet another one!

Guillermo, regarding UTF-8 conversion, just making sure you've noticed the pages in the dev docs about UTF-8: http://docs.moodle.org/dev/Category:UTF-8 Perhaps you could tidy up / add more documentation there? Alternatively, feel free to add to Derek's starter page http://docs.moodle.org/dev/Reference Although it does include /dev/ in the URL, there often seems quite an overlap in stuff of interest to developers and admins (and even teachers!) for example http://docs.moodle.org/dev/Moodle_2.3_release_notes.

Frank, I've just moved the contents of the 'UTF-8 and BOM:' pages to the 'UTF-8 and BOM' talk pages, hoping that the content can be merged. Let me know if you think it would be better moved to the dev docs.

Finally, as Derek and Guillermo both mention, I'm happy to clean up 'experiments' in any of the wikis - I'm used to cleaning up my own mess. wink

Average of ratings: -
In reply to Helen Foster

Re: Moodle documentation: "Non-Version" documentation pages

by Séverin Terrier -
Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Testers Picture of Translators

Hi Helen,

You said "Redirecting to a page in the most recent version wiki from earlier version wikis".

But this means that, when a new version (say 2.4) comes, you have to modify all (2.3) concerned pages to replace the content with redirects to the new version...

Séverin

Average of ratings: -
In reply to Séverin Terrier

Re: Moodle documentation: "Non-Version" documentation pages

by Helen Foster -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers Picture of Translators

That's correct Séverin. There are only a few pages though, so it only takes a few minutes to add redirects to each of them.

Average of ratings: -
In reply to Helen Foster

Re: Moodle documentation: "Non-Version" documentation pages

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi Séverin and Helen

Are you talking of this kind of anomalies? For example,
http://docs.moodle.org/22/en/Installing_Moodle_on_Debian_based_distributions#Setup_cron has a link http://docs.moodle.org/en/Cron_with_Unix_or_Linux which was automatically redirected to
http://docs.moodle.org/22/en/Cron_with_Unix_or_Linux. That was correct version wise.

But after making /23/ the default wiki that "version neutral" link is now redirected to http://docs.moodle.org/23/en/Cron_with_Unix_or_Linux. Now we have the situation where a /22/ wiki page referring to a /23/ wiki page, which is wrong, at least in this case.

This is one of the reasons why I did not want this page to be duplicated. See my post http://moodle.org/mod/forum/discuss.php?d=200288#p896941.
Average of ratings: -
In reply to Visvanath Ratnaweera

Re: Moodle documentation: "Non-Version" documentation pages

by Guillermo Madero -

Hi Visvanath,

As http://docs.moodle.org/23/en/Upgrading_to_Moodle_2.3 says that "You can only upgrade to Moodle 2.3 from Moodle 2.2 or later", I agreed because if a user has already read the previous pages, dealing with UTF8 should then not be an issue. However, having myself started with M 1.9.4, I  had never seen the maze that a user has to go through is he's coming from an older version! Just as a side note, I would definitely agree with the idea of having a clear, accurate and concise grid to establish from which version can be jumped directly to another.

My point of view is that only pages that are really Moodle related should be cloned, any others should remain unique.

Average of ratings: -
In reply to Dan Marsden

Re: Moodle documentation: "Non-Version" documentation pages

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
To all, who maintain "non-version" documentation pages in the current /22/ wiki,

/22/ wiki had been cloned to /23/ somewhere between 21. and 23. May. Changes to /22/ pages since then do not go into the corr. /23/ pages.
Average of ratings: Useful (1)
In reply to Visvanath Ratnaweera

Re: Moodle documentation: "Non-Version" documentation pages

by Helen Foster -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers Picture of Translators

Thanks for the mention Visvanath. It's on my to-do list to go through recent changes in the 2.2 docs and add relevant info to the 2.3 docs.

Average of ratings: -