The original Performance doc http://docs.moodle.org/en/Performance later renamed http://docs.moodle.org/19/en/Performance was excellent. It was compulsory reading n the "Hardware and Performance" forum, http://moodle.org/mod/forum/view.php?id=596, and helped very much in keeping the discussions short without compromising on information. Later came the http://docs.moodle.org/en/Performance_FAQ, which was a "stub" for some time. I started expanding it with the intention of pointing to the relevant places in the Performance doc for the standard questions in the performance forum. I tried right from the beginning not to duplicate the information which are already in the Performance doc. As a result Performance_FAQ has numerous links to Performance.
Then came the first problem, these docs started getting multiplied! Currently there are four Performance_FAQs. And this at a stage where the FAQ is a fraction of what it could be. "Coincidentally" no content has been added since then, except may be for this http://moodle.org/mod/forum/discuss.php?d=191277#p833471.
Here comes the second problem: Three of the Performance docs have been renamed or split. Now there are:
- http://docs.moodle.org/20/en/Performance_recommendations
- http://docs.moodle.org/21/en/Performance_recommendations
- http://docs.moodle.org/22/en/Performance_recommendations
- http://docs.moodle.org/20/en/Performance_settings
- http://docs.moodle.org/21/en/Performance_settings
- http://docs.moodle.org/22/en/Performance_settings
I've no problem as long as these "multiplications" won't break existing pages. Visit the following pages and see for yourselves!
- http://docs.moodle.org/20/en/Performance_FAQ
- http://docs.moodle.org/21/en/Performance_FAQ
- http://docs.moodle.org/22/en/Performance_FAQ
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Helen Foster -
Visvanath, thanks for pointing out the broken links in the Performance FAQ documentation. They've now been fixed. The links should not be broken in future multiplications.
When links to documentation are provided on moodle.org, I suggest that they are of the form Performance FAQ i.e. with no version number, as they will always go to the latest version of the page. I'm trying to keep the 2.1 and 2.2 documentation (i.e. supported stable builds) as up-to-date as possible, copying any changes in the 2.2 docs to the 2.1 docs and vice versa.
In reply to Helen Foster
Re: Moodle documentation: Performance docs in a mess
by Visvanath Ratnaweera -
Hi Helen
Thanks for your prompt response.
> I'm trying to keep the 2.1 and 2.2 documentation (i.e. supported stable builds) as up-to-date as possible, copying any changes in the 2.2 docs to the 2.1 docs and vice versa.
What about the docs for versions 1.9 and 2.0? The changes so far are valid for those too.
Do you really mean, you manually propagate changes to one version amoung the others? That would be like inheriting five door bells to kept polished - long before any of the houses become inhabitable, if ever!
You know very well where the problem lies. I don't want to go through it all over. For the sake of casual visitors, here is the history:
- "Update on Moodle 2.0 Docs" http://moodle.org/mod/forum/discuss.php?d=176065
- "Quick explaination of MoodleDocs verison migration" http://moodle.org/mod/forum/discuss.php?d=182081
I hate to leave things unfinished, but in this case, I hope others will take over the Performance_FAQ.
Thanks for your prompt response.
> I'm trying to keep the 2.1 and 2.2 documentation (i.e. supported stable builds) as up-to-date as possible, copying any changes in the 2.2 docs to the 2.1 docs and vice versa.
What about the docs for versions 1.9 and 2.0? The changes so far are valid for those too.
Do you really mean, you manually propagate changes to one version amoung the others? That would be like inheriting five door bells to kept polished - long before any of the houses become inhabitable, if ever!
You know very well where the problem lies. I don't want to go through it all over. For the sake of casual visitors, here is the history:
- "Update on Moodle 2.0 Docs" http://moodle.org/mod/forum/discuss.php?d=176065
- "Quick explaination of MoodleDocs verison migration" http://moodle.org/mod/forum/discuss.php?d=182081
I hate to leave things unfinished, but in this case, I hope others will take over the Performance_FAQ.
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Frank Ralf -
I second every word by Visvanath!
As he and others have pointed out again and again, cloning Moodle Docs is the _totally_wrong_approach_ for providing documentation for different versions of Moodle.
The suggestion to use subpages instead - which would be a transparent and maintainable solution - is still open for discussion: Sub-page transclusion (Re: Quick explanation of MoodleDocs version migration)
Unfortunately, none of the powers that be has ever commented on that suggestion
Cheers,
Frank
As he and others have pointed out again and again, cloning Moodle Docs is the _totally_wrong_approach_ for providing documentation for different versions of Moodle.
The suggestion to use subpages instead - which would be a transparent and maintainable solution - is still open for discussion: Sub-page transclusion (Re: Quick explanation of MoodleDocs version migration)
Unfortunately, none of the powers that be has ever commented on that suggestion
Cheers,
Frank
Hi,
Like you Frank, and other people i know, I also think that spliting docs in several versions (and that many versions ! ) isn't the best thing Moodle as done
Perhaps one for 1.x, one for 2.x and one for 3.x could be a better solution.
Is see a lot of bad effects, but not really much good ones, even more if you think international, and not "english only"...
I think that categories and sub-page transclusion would be very much powerfull to provide consistant and yet sometimes version specific informations.
I also have some unanswered questions in this thread since several months
Séverin
I'm inclined to agree.. I've been doing a lot of work on the installation docs recently and the proliferation of different versions is confusing. There is a redirect in place to direct the casual enquirer to the latest version but that does not mean that updates will be made in the latest version. Neither does it mean that updates will be copied back to older versions.
Worse, the confusion may lead to people thinking, "I don't know what's going on here so I won't bother".
I don't want to rock the boat but just my $00.02. I had to ask Helen to explain what was going on but most users don't have that option unfortunately. My vote would be for a 1.x version and a 2.x version - that's enough.
Worse, the confusion may lead to people thinking, "I don't know what's going on here so I won't bother".
I don't want to rock the boat but just my $00.02. I had to ask Helen to explain what was going on but most users don't have that option unfortunately. My vote would be for a 1.x version and a 2.x version - that's enough.
Thanks everyone for your comments. It's good to hear what you all think.
Regarding the 1.9 and 2.0 documentation, anyone is welcome to edit the wikis if they find it important, just like anyone is welcome to continue fixing non-security bugs in Moodle 1.9 and 2.0.
When I first heard of the plan to clone the documentation wiki for new versions, I thought it sounded crazy, however after spending time buried in the docs, I realised that the changes between 1.9 and 2.0 were so enormous (thinking of new features such as repositories and improvements to enrolments and roles) that separate wikis were really necessary. I don't see how sub-page transclusion could be used for such big changes.
Séverin, whilst I appreciate the inter-language linking problems, unfortunately I don't have any clever solutions.
The English Moodle Docs has had a huge number of contributions since it was set up 6 years ago - over 85,000 edits according to http://docs.moodle.org/19/en/Special:Statistics. It urgently needed updating and a thorough reorganisation, which it has now had. A big thank you to everyone who has helped.
Whilst the documentation will always be a work-in-progress, I don't think, from now on, that many changes will need to be made to several version wikis. We just need to keep up with the Moodle release schedule now.
In reply to Helen Foster
Re: Moodle documentation: Performance docs in a mess
by Visvanath Ratnaweera -
Helen,
I can't believe what I read, either you don't read or you don't want to listen.
> Regarding the 1.9 and 2.0 documentation, anyone is welcome to edit the wikis if they find it important, just like anyone is welcome to continue fixing non-security bugs in Moodle 1.9 and 2.0.
Means that they are in the death row?
> When I first heard of the plan to clone the documentation wiki for new versions, I thought it sounded crazy,
It still is!
> however after spending time buried in the docs, I realised that the changes between 1.9 and 2.0 were so enormous (thinking of new features such as repositories and improvements to enrolments and roles) that separate wikis were really necessary.
Can you show those differences, I mean diff /19/ /20/ contentwise, not the "door bell polishing"?
> I don't see how sub-page transclusion could be used for such big changes.
I was talking of the problem. Ready to discuss the solution once you people recognize the problem and ready to discuss a solution.
> Séverin, whilst I appreciate the inter-language linking problems, unfortunately I don't have any clever solutions.
Don't break the original, the "foriegners" will look after themselves. (Same case with German).
> The English Moodle Docs has had a huge number of contributions since it was set up 6 years ago - over 85,000 edits according to http://docs.moodle.org/19/en/Special:Statistics. It urgently needed updating and a thorough reorganisation, which it has now had.
So you cleaned up a mess by multiplying it?
> A big thank you to everyone who has helped.
They are feeling unheard.
> I don't think, from now on, that many changes will need to be made to several version wikis.
You must be joking. At least if you've read what I've wrote in this thread: "this at a stage where the FAQ is a fraction of what it could be", "like inheriting five door bells to kept polished - long before any of the houses become inhabitable, if ever!". Failing that look at all the stubs in Performance FAQ, just as an example. If you need more, I can provide much more.
I can't believe what I read, either you don't read or you don't want to listen.
> Regarding the 1.9 and 2.0 documentation, anyone is welcome to edit the wikis if they find it important, just like anyone is welcome to continue fixing non-security bugs in Moodle 1.9 and 2.0.
Means that they are in the death row?
> When I first heard of the plan to clone the documentation wiki for new versions, I thought it sounded crazy,
It still is!
> however after spending time buried in the docs, I realised that the changes between 1.9 and 2.0 were so enormous (thinking of new features such as repositories and improvements to enrolments and roles) that separate wikis were really necessary.
Can you show those differences, I mean diff /19/ /20/ contentwise, not the "door bell polishing"?
> I don't see how sub-page transclusion could be used for such big changes.
I was talking of the problem. Ready to discuss the solution once you people recognize the problem and ready to discuss a solution.
> Séverin, whilst I appreciate the inter-language linking problems, unfortunately I don't have any clever solutions.
Don't break the original, the "foriegners" will look after themselves. (Same case with German).
> The English Moodle Docs has had a huge number of contributions since it was set up 6 years ago - over 85,000 edits according to http://docs.moodle.org/19/en/Special:Statistics. It urgently needed updating and a thorough reorganisation, which it has now had.
So you cleaned up a mess by multiplying it?
> A big thank you to everyone who has helped.
They are feeling unheard.
> I don't think, from now on, that many changes will need to be made to several version wikis.
You must be joking. At least if you've read what I've wrote in this thread: "this at a stage where the FAQ is a fraction of what it could be", "like inheriting five door bells to kept polished - long before any of the houses become inhabitable, if ever!". Failing that look at all the stubs in Performance FAQ, just as an example. If you need more, I can provide much more.
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Visvanath Ratnaweera -
Hi Helen
I apologize for the harsh tone in my previous post. It was the usual dilemma. Use a political language, one can misunderstand/side step/oversee the point. Tell it directly, the other could get offended. As a foreigner I don't have much variations.
Coming back to the topic, although the discussion shifted to the policy level in a subthread, I would like to hear your arguments for multiple wikis from the point of view of documenters and document readers.
@all
Only a few have actively contributed to this burning issue. If you don't want to participate directly, could you please signal your openion by rating the posts which carry your openion as "Useful"?
I apologize for the harsh tone in my previous post. It was the usual dilemma. Use a political language, one can misunderstand/side step/oversee the point. Tell it directly, the other could get offended. As a foreigner I don't have much variations.
Coming back to the topic, although the discussion shifted to the policy level in a subthread, I would like to hear your arguments for multiple wikis from the point of view of documenters and document readers.
@all
Only a few have actively contributed to this burning issue. If you don't want to participate directly, could you please signal your openion by rating the posts which carry your openion as "Useful"?
The issue to me was not the splitting of the docs. Between 1.9 and 2.0 was completely sensible. It's having a fresh set of docs for every version of 2.x. This wouldn't have mattered in the "good old days" when a branch could last some time (years in the case of 1.9) but is a struggle when we have stampeded from 2.0 to nigh on 2.3 in a relatively short period of time.
To stir this a little more there are also the dev docs. There is only one set of dev docs (unless I've missed something) but these are the docs that *substantially* change between versions. Even worse, there are some articles that are clearly in a gray area between the dev docs and the normal docs.
You might be right - I hope you are - but it feels a bit shaky at the moment I'm afraid
To stir this a little more there are also the dev docs. There is only one set of dev docs (unless I've missed something) but these are the docs that *substantially* change between versions. Even worse, there are some articles that are clearly in a gray area between the dev docs and the normal docs.
You might be right - I hope you are - but it feels a bit shaky at the moment I'm afraid
I have to agree with Howard, the split between v1.9 and 2.0 is reasonable, but I doubt the differences between v2.1 and 2.3 are not going to be that great they require separate documentation. Additional or refined documentation, certainly, but not separate. It is, after all, only the changes that we really want to document, not the ongoing elements, why reinvent the wheel? It would also make it easier to maintain them, I suggest.
The thing that concerns me is that it is becoming increasingly difficult to actually find what you are looking for via any kind of menu within the docs. You can find so many things, but there is so much more that does not even make it to the menus on the first page of each version. I suspect this will kill the incentive to create and maintain some of those really helpful docs. What will be the point of writing somethng up if no-one can find it? It is all about organization of information, and the restrictions placed on that organization has left a lot of people wondering.
Breaking Dev docs away from Admin and User docs also makes sense, but there needs to be clear distinctions here between what can be an Admin doc, applying to a site, and a User doc, applying to a course (as an editor or a non-editor). That is not clear right now, and I am not sure it ever was despite the previous structure.
Howard is also right when he suggests that there are a lot of "gray" areas between different types of docs. Perhaps the older structure, while not perfect, was a better approach.
To be honest, I haven't looked at the dev docs at all because I figured I wouldn't understand them. I think the distinctions between admin and user (ie, course editor) are ok in the documentation, but maybe I am looking at it from a different angle, being a bit of an admin and a bit of a course editor. In terms of it being difficult to find what you want I think the issue is to get better search facilities - and whenever people come on the forums saying they couldn't find any help in the docs, I always ask them which terms they used to try to find what they wanted. I don't like the search box and it doesn't always take me to where I wanted to go.
Maybe I am the only person who actually thinks having different docs for different versions is a good idea, but I do. For sure, there aren't that many changes between versions but if we kept to only 2.0 docs, we'd have to keep adding "only for 2.1/.2.3") each time a new feature came up - and then -for instance- when the assignment module is completely redone we'll have to have two lots of pages, one for pre-new assignment module and one for post-new assignment module. Much better surely to have a wiki for each version that only has the stuff in for that version? As the documentation gets more complete (well, ok, never complete, but more in depth) you'll just need to update the latest version.
In reply to Mary Cooch
Re: Moodle documentation: Performance docs in a mess
by Visvanath Ratnaweera -
Hi Mary
You wrote:
> but if we kept to only 2.0 docs, we'd have to keep adding "only for 2.1/.2.3") each time a new feature came up
Really? Can you show me the differences amoung
http://docs.moodle.org/20/en/Beginning_Moodle_2.0_Administration
http://docs.moodle.org/21/en/Beginning_Moodle_2.0_Administration
http://docs.moodle.org/22/en/Beginning_Moodle_2.0_Administration
OK, you may argue that they are all about Moodle 2.0. Then where are
http://docs.moodle.org/21/en/Beginning_Moodle_2.1_Administration
http://docs.moodle.org/22/en/Beginning_Moodle_2.2_Administration ?
You wrote:
> but if we kept to only 2.0 docs, we'd have to keep adding "only for 2.1/.2.3") each time a new feature came up
Really? Can you show me the differences amoung
http://docs.moodle.org/20/en/Beginning_Moodle_2.0_Administration
http://docs.moodle.org/21/en/Beginning_Moodle_2.0_Administration
http://docs.moodle.org/22/en/Beginning_Moodle_2.0_Administration
OK, you may argue that they are all about Moodle 2.0. Then where are
http://docs.moodle.org/21/en/Beginning_Moodle_2.1_Administration
http://docs.moodle.org/22/en/Beginning_Moodle_2.2_Administration ?
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Frank Ralf -
@Mary
IMHO "... adding 'only for 2.1/.2.3' each time ..." isn't a bug, it's a feature because it points out the differences between Moodle versions and thus helps learning.
Structuring the wiki should be done using MediaWiki powerful features like categories, templates, subpages and transclusion (as used to be done in the good old times, when there was only one Moodle Docs ...). See "Sub-page transclusion (Re: Quick explanation of MoodleDocs version migration)" for a detailed description.
That way you can keep all documentation belonging to a certain topic together and move older documentation out of sight but not out of reach.
IMHO "... adding 'only for 2.1/.2.3' each time ..." isn't a bug, it's a feature because it points out the differences between Moodle versions and thus helps learning.
Structuring the wiki should be done using MediaWiki powerful features like categories, templates, subpages and transclusion (as used to be done in the good old times, when there was only one Moodle Docs ...). See "Sub-page transclusion (Re: Quick explanation of MoodleDocs version migration)" for a detailed description.
That way you can keep all documentation belonging to a certain topic together and move older documentation out of sight but not out of reach.
Hi,
I think that:
- most pages stay the same beetween Moodle 2.0, 2.1 and 2.2 (and soon 2.3)
- it's not a problem (at least for me and other people) to have versions specific sections (or pages) : most of the time, new versions implies new features, thus new pages. There are rare cases (like Assignment in 2.3) where creating a (completly) new page would be necessary.
- i would better keep a doc for versions < 2, another for all Moodle 2.x (, another one for Moodle 3.x when it comes), and a developper one.
I hope these "Most Wanted Pages - Docs 2, June 2011" http://moodle.org/mod/forum/discuss.php?d=177060 have been found prior to cloning?
At the risk of excessively labouring the point, I meant to add....
The fact that there *are* multiple wikis and how they are organised is only obvious once you have had it explained to you. I don't consider myself entirely stupid (answers on a postcard) but this wasn't immediately obvious to me - I, like almost every other docs user, had missed the announcement/discussion.
I think most user's assumption will be that there is only one Wiki (normal - like every other project I can think of). As this is not the case, whatever we do, we need to be super careful to properly manage user's expectations. That is, not leave them hanging thinking, "what the hell is going on here??"
The fact that there *are* multiple wikis and how they are organised is only obvious once you have had it explained to you. I don't consider myself entirely stupid (answers on a postcard) but this wasn't immediately obvious to me - I, like almost every other docs user, had missed the announcement/discussion.
I think most user's assumption will be that there is only one Wiki (normal - like every other project I can think of). As this is not the case, whatever we do, we need to be super careful to properly manage user's expectations. That is, not leave them hanging thinking, "what the hell is going on here??"
Visvanath, thanks for your post and sorry for my delay in replying to your comment about wanting to hear my arguments for multiple wikis.
When I investigated how other projects were organising their documentation, I found that in a lot of cases documentation was separated into different versions, for example the Apache documentation, the Ubuntu documentation, the Koha Library Software documentation and the MySQL documentation.
I mentioned in my previous post about the enormous changes between 1.9 and 2.0. In Moodle 1.9 users had to be assigned roles in a course; in 2.0 this is now handled by different enrolment methods. File handling is completely different in 2.0, with the file picker and repositories; navigation is another big difference. There was really no way that transclusion could have worked for all of these differences.
Howard, as you point out, we need to make it much clearer that documentation is available for different versions. The main page of each wiki now lists links to documentation for other versions. As Martin mentions, we also need to improve navigation between the different versions (MDLSITE-1369). If anyone has any more ideas for improving the docs user experience they would be most welcome.
I can still remember first wandering through the documentation for 1.x and taking a while to learn that there were various active versions and the documentation varied with the version.
I got to documentation using Google, which is to say I never came in through the front page, which now very clearly states up front, at the top (and blinking marquee would be helpful ) that there are different versions with separate documentation.
I am thinking the newbs will always arrive the way I did, but, if they are going to ever ask a question, they have to register. And the response message to registration is the one time a user is actually going to read the whole message.
Hi Ben,
Good point about arriving in the docs via Google. How about a message at the top of each page with links to documentation for other versions (like the Dovecot Wiki does), instead of the 'more docs' block at the bottom of the page?
"And the response message to registration is the one time a user is actually going to read the whole message."
Sorry I'm confused about what you mean by the above sentence. Please could you explain.
Hi,
It would certainly be more visual to have this kind of link at the top (better than at bottom) !
And it's the same for "Other langages" links, search...
In fact, having a (more docs) link for over versions is one thing. But what i really don't like (and find useless) is that it always point to the home page. A useful link would point to the same page, if it exists ! (same name)
I agree that the most useful link would be to the same page for other versions, but, if the choice is between knowing there are other versions and the link taking me to the home page of that version and not knowing at all that there are other versions, I'll go with the home page link.
If you go to, say http://docs.moodle.org/22/en/Authentication and try clicking on the more docs links for 2.1, 2.0 and 1.9, you'll find that they no longer lead to the main page of each version wiki - yay!
Apologies for taking so long to figure out how to make this improvement. Now I just need to work on getting the links moved to the top of the page.
Thanks again for your feedback everyone. It's always appreciated, even though we may be slow in making changes.
Nice change, thanks Helen
I totally agree. And, what's more, I wish I had read about this 2 hours ago when I couldn't get to the 1.9 about My Moodle.
Well done, indeed!
Oh, I like that red background at the top of Dovecot Wiki!
What I meant, Helen, is that, after you register on moodle.org and have done a few things, the slew of emails from the different forums gets huge. I usually check subject headers and read only about 1/3 of those messages.
But, the very first registration message gets a lot of attention. It gets read thoroughly, if there's useful content in it. (Mine was the old, "do something in your profile," which wasn't very useful. So, the first message is a good place to warn newbies that there are different versions of the documentation.
Thanks Ben, great suggestion to customize the course welcome message. I'll definitely do that.
Helen and others
May be an over elaboration on my part, but I went through this yesterday and want it documented.
I use my user page in the docs for testing. Yesterday it went "missing": I logged in to the docs wiki, klicked on my name, and it says "no such account" (Das Benutzerkonto ... ist nicht vorhanden). I was going to create a new one reluctantly when I realized that I'm in /20/ wiki! I have started navigating the docs in an article in the /20/ wiki and as a result logged in to that wiki.
That is not the end of the story. I changed /20/ to /22/ in the URL field, found the old page, started to edit. It says I'm not logged in! Yes, I'm supposed to login to /22/ wiki separately! Is this possible?
May be an over elaboration on my part, but I went through this yesterday and want it documented.
I use my user page in the docs for testing. Yesterday it went "missing": I logged in to the docs wiki, klicked on my name, and it says "no such account" (Das Benutzerkonto ... ist nicht vorhanden). I was going to create a new one reluctantly when I realized that I'm in /20/ wiki! I have started navigating the docs in an article in the /20/ wiki and as a result logged in to that wiki.
That is not the end of the story. I changed /20/ to /22/ in the URL field, found the old page, started to edit. It says I'm not logged in! Yes, I'm supposed to login to /22/ wiki separately! Is this possible?
Hi Visvanath,
The problem with user pages has been reported before. User pages are to be kept (only) in the Dev Docs:
* User page in docs
* Stop cloning Moodle Docs!
* Using sub pages of own user page for testing, etc.
I even created a template to clean up the mess:
http://docs.moodle.org/dev/Template:Back_from_dev
(I have to admit that I'm about to give up on Moodle Docs ...)
Frank
The problem with user pages has been reported before. User pages are to be kept (only) in the Dev Docs:
* User page in docs
* Stop cloning Moodle Docs!
* Using sub pages of own user page for testing, etc.
I even created a template to clean up the mess:
http://docs.moodle.org/dev/Template:Back_from_dev
(I have to admit that I'm about to give up on Moodle Docs ...)
Frank
Frank "I have to admit that I'm about to give up on Moodle Docs ..."
That would be unfortunate... but understandable.
Joseph
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Visvanath Ratnaweera -
Helen,
Two things I've forgotten to mention in my previous post:
You wrote:
> When links to documentation are provided on moodle.org, I suggest that they are of the form Performance FAQ i.e. with no version number, as they will always go to the latest version of the page.
Not always. Out of the following list, the ones with a version in front work, the one without a version does not:
- http://docs.moodle.org/19/en/index.php?title=Special%3ASearch&go=Go
- http://docs.moodle.org/20/en/index.php?title=Special%3ASearch&go=Go
- http://docs.moodle.org/21/en/index.php?title=Special%3ASearch&go=Go
- http://docs.moodle.org/22/en/index.php?title=Special%3ASearch&go=Go
- http://docs.moodle.org/en/index.php?title=Special%3ASearch&go=Go (The requested page title was invalid, empty, or an incorrectly linked inter-language or inter-wiki title. It may contain one or more characters which cannot be used in titles.)
> I'm trying to keep the 2.1 and 2.2 documentation (i.e. supported stable builds) as up-to-date as possible, copying any changes in the 2.2 docs to the 2.1 docs and vice versa.
Suppose somebody makes a change in /21/ and _means_ /21/? (That is the whole idea of splitting the docs, isn't it?) By changing /22/ back-and-forth will turn the intended propagation to a standing wave! (I'm not challenging your jugement. But Performance FAQ is not the only page you have to maintain this way. I can imagine you recruiting an "editing staff" for this work.)
Two things I've forgotten to mention in my previous post:
You wrote:
> When links to documentation are provided on moodle.org, I suggest that they are of the form Performance FAQ i.e. with no version number, as they will always go to the latest version of the page.
Not always. Out of the following list, the ones with a version in front work, the one without a version does not:
- http://docs.moodle.org/19/en/index.php?title=Special%3ASearch&go=Go
- http://docs.moodle.org/20/en/index.php?title=Special%3ASearch&go=Go
- http://docs.moodle.org/21/en/index.php?title=Special%3ASearch&go=Go
- http://docs.moodle.org/22/en/index.php?title=Special%3ASearch&go=Go
- http://docs.moodle.org/en/index.php?title=Special%3ASearch&go=Go (The requested page title was invalid, empty, or an incorrectly linked inter-language or inter-wiki title. It may contain one or more characters which cannot be used in titles.)
> I'm trying to keep the 2.1 and 2.2 documentation (i.e. supported stable builds) as up-to-date as possible, copying any changes in the 2.2 docs to the 2.1 docs and vice versa.
Suppose somebody makes a change in /21/ and _means_ /21/? (That is the whole idea of splitting the docs, isn't it?) By changing /22/ back-and-forth will turn the intended propagation to a standing wave! (I'm not challenging your jugement. But Performance FAQ is not the only page you have to maintain this way. I can imagine you recruiting an "editing staff" for this work.)
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Martin Dougiamas -
Some quick thoughts on the whole thread here:
Transclusion ... no. We tried it out, and rejected it. I think this would be a far more unpopular and confusing choice than simple separate wikis per version which is at least something that most people who aren't developers can understand.
What those here might have forgotten was that the old single wiki was a total mess. Different versions smushed onto one page, inaccurate and misleading info. It was a nightmare for users to navigate. And yes, to use performance as an example, there are huge differences between 1.9 and 2.2.
The path I've chosen here (and I had to convince Helen initially too ) of separate wikis is the best scenario of the bunch (I'm not saying it's perfect but it's the best we can support). The update process is simple, users get to see exactly what they need to, and not what they don't. The wikis are much smaller now, and the differences are much smaller now.
Not every doc change needs to be ported back to older versions all the time. Just edit the most recent one (2.2). I'm not too concerned about users of older versions of Moodle missing out on a few edits here and there. It's still much more complete now than it ever was, and those users will be on the newer versions soon enough.
What I think we need to do is go forward, not back, and make more changes to improve
- education of users about the different versions
- navigaton between different versions
My suggestion is mainly about using sub-pages which can be transcluded but don't need to be. See http://docs.moodle.org/20/en/User:Frank_Ralf/Subpage_transclusion for an example.
In reply to Martin Dougiamas
Re: Moodle documentation: Performance docs in a mess
by Visvanath Ratnaweera -
Hi Martin
Thanks for joining with this background information which I was not aware of.
I too went through the discusssion again and observe that it takes lot of side tracks. Even the main topic, that of the multiple wikis, is an issue not a cause. I have the feeling that the origin is here:
<quote>I'm not too concerned about users of older versions of Moodle missing out on a few edits here and there. It's still much more complete now than it ever was, and those users will be on the newer versions soon enough.</quote>
There is an urge to move to 2.latest, which is 2.2 right now!
Why?
I am not saying, I don't need the new features in 2.x. In fact, a large group of teachers are waiting to upgrade to 2.x expecting the new file handling to solve a weakness 1.9 had - the course based files. I am surprised to learn that I need Alfresco for that! (Details here http://moodle.org/mod/forum/discuss.php?d=191894 ) Not that I don't want Alfresco, may be it a good idea in the long run (these users have sophisticated requiremets on their files), but if that is the case, I could have solved their problem a long time ago, still under 1.9! (If I am wrong, please correct me in the thread mentioned.)
Apart from that, as a co-mod in the Hardware and Performance forum, resources is an important topic to me. The move from 1.9 to 2.0 was not the best in this respect. I'm in a luxurious position that I can afford beefy dedicated servers, but most of the visitors to the performance forum don't. Many who have been running 1.9 without problems suddenly have performance issues in 2.x.
Is there any possiblity of extending the life time of 1.9? How expensive would it be to assign somebody just to keep the security and critical bugs (if any) fixed?
Thanks for joining with this background information which I was not aware of.
I too went through the discusssion again and observe that it takes lot of side tracks. Even the main topic, that of the multiple wikis, is an issue not a cause. I have the feeling that the origin is here:
<quote>I'm not too concerned about users of older versions of Moodle missing out on a few edits here and there. It's still much more complete now than it ever was, and those users will be on the newer versions soon enough.</quote>
There is an urge to move to 2.latest, which is 2.2 right now!
Why?
I am not saying, I don't need the new features in 2.x. In fact, a large group of teachers are waiting to upgrade to 2.x expecting the new file handling to solve a weakness 1.9 had - the course based files. I am surprised to learn that I need Alfresco for that! (Details here http://moodle.org/mod/forum/discuss.php?d=191894 ) Not that I don't want Alfresco, may be it a good idea in the long run (these users have sophisticated requiremets on their files), but if that is the case, I could have solved their problem a long time ago, still under 1.9! (If I am wrong, please correct me in the thread mentioned.)
Apart from that, as a co-mod in the Hardware and Performance forum, resources is an important topic to me. The move from 1.9 to 2.0 was not the best in this respect. I'm in a luxurious position that I can afford beefy dedicated servers, but most of the visitors to the performance forum don't. Many who have been running 1.9 without problems suddenly have performance issues in 2.x.
Is there any possiblity of extending the life time of 1.9? How expensive would it be to assign somebody just to keep the security and critical bugs (if any) fixed?
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Howard Miller -
This is really an entirely separate issue, but there does seem to be an underlying disconnect between those who are (quite understandably) pushing forward with the 2.x branch and those of us out on the "front line". I am *still* writing much more 1.9 code than I am 2.x code for custom developments. While new users are happily picking up 2.2, existing 1.9 users continue to show reluctance to move. Mostly because they don't see any benefit for them.
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Martin Dougiamas -
Moodle HQ has been pouring precious resources into 1.9 for nearly 5 years now (including the development time before it released), and will keep doing so for another 6 months. As far as I am concerned, that's a lot.
It's there, it's very stable, and you can continue to use it as long as you want. If you want to have someone supporting it for even longer, though, you'll have to rely on broader community support.
I am totally focussed on making Moodle 2.x better and better, based on feedback. File handling is one the top priorities for 2.3, for example.
About performance issues, it's really not very clear where the problems are. Many are not having problems, and some are having problems in areas that suggest poor tuning. I'm extremely keen to fix performance problems as they are identified. Petr Skoda is the component lead in the tracker of all performance issues and will deal with them.
In reply to Martin Dougiamas
Re: Moodle documentation: Performance docs in a mess
by Visvanath Ratnaweera -
Hi Martin
I shouldn't have connected these two things after all.
About the accelerated release plan and shorter support periods for older versions: I trust that HQ weighed all pros and cons chosen the best path for Moodle. And I don't want to dilute the value of the software from your foundry by restating the well-known. In any case, this was not the subject of this discussion.
My original issue was the problems I had maintaining Performance FAQ due to a) cloning of wikis b) the following renaming of the Performance document page. After recognizing that cloning of wikis is a major disruption in the documentation the discussion focused on that. (For the casual visitor: see the other subthread, the discussion with Helen, for pointers on what those disruptions are.)
So far four solutions were suggested in this forum. In the order of complexity, they are:
1. My own trivial solution: one wiki (no /XY/ in the URL)
http://moodle.org/mod/forum/discuss.php?d=176065#p779435
2. Transclusion, initially suggested by Frank Ralf
http://moodle.org/mod/forum/discuss.php?d=176065#p779453
3. One wiki for major versions only
Suggested by many. Also the policy of German and French wikis (amoung others, may be)
4. One wiki for each minor version
Already implemented in the original (english) documentation, triggering this discussion.
There could be a remote connection between the two topics mentioned at the beginning - that of resources. Actively maintaining four major versions and working on the fifth is no simple task. Compared to that just documenting the work should be trivial, one would think. Sorry, but the sysiphus work being done right now is home made.
P.S. Just a point of caution. There is also the /dev/ wiki. I don't want to make the discussion more complicated that it already is. But pl. keep an eye on that. The worst scenario is to solve the present problem and to find out that the new solution collides with the /dev/ wiki.
I shouldn't have connected these two things after all.
About the accelerated release plan and shorter support periods for older versions: I trust that HQ weighed all pros and cons chosen the best path for Moodle. And I don't want to dilute the value of the software from your foundry by restating the well-known. In any case, this was not the subject of this discussion.
My original issue was the problems I had maintaining Performance FAQ due to a) cloning of wikis b) the following renaming of the Performance document page. After recognizing that cloning of wikis is a major disruption in the documentation the discussion focused on that. (For the casual visitor: see the other subthread, the discussion with Helen, for pointers on what those disruptions are.)
So far four solutions were suggested in this forum. In the order of complexity, they are:
1. My own trivial solution: one wiki (no /XY/ in the URL)
http://moodle.org/mod/forum/discuss.php?d=176065#p779435
2. Transclusion, initially suggested by Frank Ralf
http://moodle.org/mod/forum/discuss.php?d=176065#p779453
3. One wiki for major versions only
Suggested by many. Also the policy of German and French wikis (amoung others, may be)
4. One wiki for each minor version
Already implemented in the original (english) documentation, triggering this discussion.
There could be a remote connection between the two topics mentioned at the beginning - that of resources. Actively maintaining four major versions and working on the fifth is no simple task. Compared to that just documenting the work should be trivial, one would think. Sorry, but the sysiphus work being done right now is home made.
P.S. Just a point of caution. There is also the /dev/ wiki. I don't want to make the discussion more complicated that it already is. But pl. keep an eye on that. The worst scenario is to solve the present problem and to find out that the new solution collides with the /dev/ wiki.
Hi Visvanath,
Regarding your point:
"3. One wiki for major versions only
Suggested by many. Also the policy of German and French wikis (amoung others, may be)"
I understand from the German documentation team that they are also planning on having separate wikis for Moodle 2.1, 2.2... Once they give the word, the 2.0 German wiki will be copied to create the 2.1 wiki.
As for the French documentation, I haven't heard of anyone wishing to change from the current combined versions wiki. Séverin, please correct me if I'm wrong!
Hi,
Talking about the french documentation, there is an open discussion, but, generaly speaking, nearly nobody involves in the doc
For the moment, we('ll) stay to only 1 version !
And i personnally think that, if we change, that would only be to make a <=1.9 version, and a >= 2.0 version...
But, as i already said in another thread, having only one french version, and several english versions (or the opposite) implies a lot of problems...
Hi Séverin,
A public thank you for all the work you, Nicolas Martignoni and the few others do on the French docs.
Also for the pleasure of writing to you for once in English.
Amicalement,
Glenys
Hi Helen
You wrote:
> I understand from the German documentation team that they are also planning on having separate wikis for Moodle 2.1, 2.2... Once they give the word, the 2.0 German wiki will be copied to create the 2.1 wiki.
This is the status of the German wiki: They have two wikis http://docs.moodle.org/19/de/ and http://docs.moodle.org/20/de/. URSs http://docs.moodle.org/21/de/, http://docs.moodle.org/22/de/ andhttp://docs.moodle.org/23/de/ are redirected to /20/. "Once the /20/ is stable it will be copied to /21/, /22/, etc." http://moodle.org/mod/forum/discuss.php?d=197165#p860118.
They tend to look at Performance docs as a developer topic which they won't translate http://moodle.org/mod/forum/discuss.php?d=197165#p860960. That could be an exit to the mess we have.
You wrote:
> I understand from the German documentation team that they are also planning on having separate wikis for Moodle 2.1, 2.2... Once they give the word, the 2.0 German wiki will be copied to create the 2.1 wiki.
This is the status of the German wiki: They have two wikis http://docs.moodle.org/19/de/ and http://docs.moodle.org/20/de/. URSs http://docs.moodle.org/21/de/, http://docs.moodle.org/22/de/ andhttp://docs.moodle.org/23/de/ are redirected to /20/. "Once the /20/ is stable it will be copied to /21/, /22/, etc." http://moodle.org/mod/forum/discuss.php?d=197165#p860118.
They tend to look at Performance docs as a developer topic which they won't translate http://moodle.org/mod/forum/discuss.php?d=197165#p860960. That could be an exit to the mess we have.
In reply to Visvanath Ratnaweera
Re: Moodle documentation: Performance docs in a mess
by Frank Ralf -
My thumbs up for suggestion 1) using sub-pages for each version, e.g. docs.moodle.org/Administration/19, docs.moodle.org/Administration/20, docs.moodle.org/Administration/21 etc.
That way, suggestion 2) - transclusion of sub-pages - could be added anytime transparently. See http://docs.moodle.org/22/en/User:Frank_Ralf/Subpage_transclusion for an example of this powerful and transparent MediaWiki feature.
A recent example how the documentation cloning makes quite a mess of the Dev Docs can be found at "Moodle 1.9 Database API Documentation".
Frank
That way, suggestion 2) - transclusion of sub-pages - could be added anytime transparently. See http://docs.moodle.org/22/en/User:Frank_Ralf/Subpage_transclusion for an example of this powerful and transparent MediaWiki feature.
A recent example how the documentation cloning makes quite a mess of the Dev Docs can be found at "Moodle 1.9 Database API Documentation".
Frank