Moodle documentation: Quick explaination of MoodleDocs verison migration

Moodle documentation: Quick explaination of MoodleDocs verison migration

by Chris Collman -
Number of replies: 14

Martins post on 1 June said that 2.1 would get its own version of Moodle Docs in the future.   Now I understand an earlier post about editing things in 2 places.

I have been merrily thinking that 2.1.x would slowly cover 2.0 just like 1.6 eventually got buried by 1.9 docs. So I have not bothered to look at my 2.0.x Moodles and put my focus upon my 2.1 soon to be production versions.   MoodleDocs sop is to use demo.moodle.net, which just happens to be 2.1, so I don't have a standard for 2.0 anymore.   Oh well.

Not going to stop my editing. File Picker and Quiz need TLC and we use those things in the 3 new webservers and 2.1 Moodles I just finished building.  The first goes live next month, and the other two a couple of weeks later.

Just curious,

Best  Chris

Average of ratings: -
In reply to Chris Collman

Re: Moodle documentation: Quick explaination of MoodleDocs verison migration

by David Barrett -

Hi, Chris

Don't know if this makes you happy, but at the keynote Martin gave at the Moodle Moot in Sydney last week, he said that each new iteration of Moodle – 2.1, 2.2, etc., would have its own set of docs. Don't know whether I was misheard or misinterpreted.

Cheers
David
smile 

Average of ratings: -
In reply to Chris Collman

Re: Moodle documentation: Quick explaination of MoodleDocs verison migration

by ben reynolds -

Pleading for the 2.1 documentation.

You do good work, Chris. I happened upon some relatively old stuff about Windows Moodle (Moodle for Windows?) 2 weeks ago, and found it not only useful but interesting.

Now I'm on Windows for 2.1, and wishing I knew more.

Oh, and any documentation about file picker would be helpful. The latest I have seen (general development forum, I think) totally intimidates me.

Average of ratings: -
In reply to ben reynolds

Re: Quick explanation of MoodleDocs version migration

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,

It is indeed correct that we will have a documentation wiki for Moodle 2.1 (and all future versions). However, the Moodle 2.0 wiki really needs tidying up and documentation of Moodle 2 features such as the file picker needs adding before we copy it to create the 2.1 Moodle Docs.

As always, any help is much appreciated. Tomaz's notes on what needs doing are available here: Page notes. Moodle Docs is definitely on my to-do list for the coming month or two!

Average of ratings: -
In reply to Helen Foster

Quo vadis, Moodle Docs? (WAS: Quick explanation of MoodleDocs version migration)

by Frank Ralf -
Creating more and more redundant and largely overlapping content by cloning Moodle Docs for each minor release creates lots of serious issues regarding keeping all this documentation in sync and up to date and IMHO is the road to documentation maintenance hell.

See the following threads for still open questions regarding this approach:

* Update on Moodle 2.0 Docs
* Back-porting of new documentation?
* Moodle docs filter

IMO the better approach would be to use MediaWiki's inherent features to avoid redundant content, see http://docs.moodle.org/20/en/MoodleDocs:Transclusion

Frank
Average of ratings: -
In reply to Frank Ralf

Re: Quo vadis, Moodle Docs? (WAS: Quick explanation of MoodleDocs version migration)

by Chris Collman -

Hi  hard working MoodleDoc'ers,

I wrote some notes to myself at User:Chris_collman after talking with Helen yesterday.   There are a few new perspectives that will help me with future edits on the page format level and in refocusing pages when they need it in the 2,0 version.

I also put in a couple of opinions/guesses about the "transition" we are going through in our documentation from a single edition that spans5 or more Moodle versions, to editions dedicated to 1 version of Moodle.  

One would hope 2.3 does not just include just a couple of new theme improvements over 2.2.   We have all see software releases of "new" versions are just tweaks of the pervious version. Likewise, I would hope (after the transition) we have not left out many key points that were in 2.0 documentions and need to be placed all editions up the the current one.  However, both these things are  going to happen. to some degree. 

And I can also completely agree that as an editor/tweaker, the transition from 1 editiion fits all to seperate editions is rather like making the trip across the River Styx 3 times just to get to the (alleged) 2.2 promise land ! big grin  

However, speaking as a very recently retired 1.5 user/site administrator/teacher, it is also annoying to have to wade through all the 1.6 to 1.9 garbage to get a clue about my version.  And hope that some  editor did not reword my clue because  they thought it was not accurate (in at least the last 2 versions of Moodle).    And I bite my virtural tounge when somebody implies that is the price I must pay for not upgrading on a regular basis. 

Looking forward, the change is about customer service and ease of use for a diverse community.   And we all know change can be ..... interesting.

Time to stack some wood and harvest some zucchini before work.  Best to all -Chris

 

Average of ratings: -
In reply to Helen Foster

Re: Quick explanation of MoodleDocs version migration

by Derek Chirnside -

Helen,

  1. I think Ralf's point of view on this has some merit. I've suggested there are between 30 and 60 critical pages that could benefit from the tranclusion approach.
  2. As well as Tomaz's work (linked in your post) Martin has said "I plan to be personally getting stuck into these  . .   to wrangle them to the ground a bit more, removing duplicates and so on. At the same time will develop a clearer TODO list for further development"  Some sort of priority list like this could benefit.  Page notes is opressively long.
  3. I've hung back a little with Tomaz going, and expecting something more definitive in the way of a plan.  I know it is a wiki, working on docs is good, but I don't think we are quite there with a plan yet.

And as Ralf said, there are unfinshed treads here, and hanging discussions.

What about a barn raising wiki week?  A list of 80 pages we sign up to work on?  But neither of these solutions will work unless there is greater clarity wth a plan.  IMO.

-Derek

 

Average of ratings: -
In reply to Derek Chirnside

Re: Quick explanation of MoodleDocs version migration

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

I'm farely new to the documentation side. Therefore my observations could be completely wrong. I'm open for corrections.

- The decision to multiply the documentation wikis by the number of supported Moodles versions http://moodle.org/mod/forum/discuss.php?d=176065#p778735 is a disaster. I hope, Martin will reconsider it.

- Frank's solution to it http://docs.moodle.org/20/en/MoodleDocs:Transclusion may or may not be the right thing. I had a simpler suggestion http://moodle.org/mod/forum/discuss.php?d=176065#p779435 which may be too rudimentary for the folk here.

- The distributed development model in the wiki is good to collect raw material. It has now reached a point where the intelligence of a single mind is necessary to merge them, if I may use the version control analogy. It follows that efforts like requesting people to add more content including the wiki week are futile at the present state. There are also no technical replacements for the merging "intelligence" I'm talking of.

- I believe Tomaz was the person in charge. What is the state since he left http://moodle.org/mod/forum/discuss.php?d=181249 ?

Yes, there are right now too many unanswered questions to ask people to just keep on contributing to the wikis.
Average of ratings: -
In reply to Visvanath Ratnaweera

Re: Quick explanation of MoodleDocs version migration

by Chris Collman -

Hi,

Splits between major versions makes sence to me.  Thus a "new" MoodleDoc for 1.x and 2.x and 3.x is my recommendation right now. smile  Getting granular with 2.0, 2.1 2.2 and ect is nice but it is a lot of work when it changes in 2.0 and 2.1 (see blank pages comment below).

Right now MoodleDocs 2.0 has lots of blank pages, in part because of the reorganization.    Blank and short pages was pretty typical back in, surprise, 2006 (8,000+ edits for me ago) and it took a lot of time.

The transclusion works in the documentation but it  requires some level of expertise and paying attention.   Maybe if we could tag it so that when it appears, it has visiual indicator in the non-edit mode that it comes from somewhere else.   Ditto, the orginal version, we need a tag in the edit mode to indicate it is used elsewhere.  The code should do that but....

I do see a inconsistancy in the big picture theory in having only a 2.1 demo.moodle, while we are susposed to be writing for 2.0 and using demo.moodle as our standard for screen shots and documentation.  This is a minor point.

Historically, I do remember 2006 and the development of MoodleDocs took a while to get the basics.  Then we got into the 'don't tell me just the settings, but how to make the settings work for me' phase after MoodleDocs matured (2009?).  Version 2.x is sort of like jumping from 1.4 to 1.8.  It will take less time but still a significant amount of time to get it to the point where we can have the "give me some examples" discussions .   My 2 cents worth.  

FYI: I am not going to backtrack with my documentation if we do a copy of 2.0 and call it 2.1 MoodleDocs.  I am using 2.1, so I am going to stick with that version until we update our Moodles, then I will look at documentation to see if it meets my needs.   I might use transclusion if I made corrections in 2.1 that work in 2.4 and the 2.3 MoodleDocs did not receive my TLC smile 

It is what is and I am going to do what I am going to do in MoodleDocs.  That is the tradition and the rules.   It is fairly obvious that MoodleDocs 2.x needs to mature (needs lots of hours of editing as it is on 2 Aug 2011) before a split should be considered. 

Help docs are a different kettle of fish.  There a split between versions does make sence, as it does in DEV.

Staying positive!   Chris

 

 

Average of ratings: -
In reply to Chris Collman

Sub-page transclusion (Re: Quick explanation of MoodleDocs version migration)

by Frank Ralf -
Transclusion might seem to be a bit tricky on first sight but in fact is totally transparent when editing a transcluded section.

Documentation for multiple versions of Moodle is a two dimensional documentation space, e.g. there's documentation on "Administration" and "Installation" for Moodle 1.9 and 2.0 respectively.

As it is now, all documentation for a certain Moodle version is kept together in its own (initially) cloned wiki, so you find information on a certain topic like "Administration" at seperate places "http://docs.moodle.org/19/en/Administration" and "http://docs.moodle.org/20/en/Administration" respectively.

IMHO the better approach would be to keep all information on a certain topic within only one wiki and put information regarding only certain versions of Moodle on their own subpages so the example above would become "http://docs.moodle.org/en/Administration/19" and "http://docs.moodle.org/en/Administration/20" respectively (see Visvanath Ratnaweera's comment on this: "... the version dependency of the documentation belongs to the last leg of the hierarchy.").

This approach provides several advantages:

  1. Only one wiki needed.
  2. All topic related information in one place.
  3. Version related information on it's own subpage.


These version related subpages could exist on their own, especially if there are big changes and differences between versions, or be transcluded in the main article page. See http://docs.moodle.org/20/en/User:Frank_Ralf/Subpage_transclusion for an example.

The only disadvantage of subpages is that they are not automatically linked from their main page. But this issue could be solved by the use of templates if there's a consistent naming pattern for subpages (i.e. Moodle version number).

There are also quite some powerful extensions for MediaWiki which could be of use here, see Extension "SubPageList3" for Moodle Docs? and Dynamic Page List (MediaWiki extension).

I hope this will move things forward smile

Frank
Average of ratings: -
In reply to Frank Ralf

Stop cloning Moodle Docs!

by Frank Ralf -
Now that Moodle 2.1 Docs (yet another clone!) is out, things get worse once again: Now there's three clones of my user page:

* http://docs.moodle.org/19/en/User:Frank_Ralf
* http://docs.moodle.org/20/en/User:Frank_Ralf
* http://docs.moodle.org/21/en/User:Frank_Ralf

I had just decided to keep the 2.0 the current one, now I will have to switch to 2.1 (until the next clone is out...).

(I use this opportunity to bump my suggestion above to use sub-pages instead of cloning from some time ago which unfortunately has gotten no reaction so far.)

Frank

JFTR: Update on Moodle 2.0 Docs

Average of ratings: -
In reply to Frank Ralf

Re: user pages in Moodle Docs

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 Frank,

We've not yet figured out a good solution for user pages, though one possibility is to only have user pages in the dev wiki. User pages in the user wikis could redirect to the dev wiki, as David Mudrak has done by adding the code

#redirect ((:dev:David Mudrak))

(replacing the curved brackets with square brackets)

to http://docs.moodle.org/20/en/User:David_Mudrak

Average of ratings: -
In reply to Frank Ralf

Re: Stop cloning Moodle Docs!

by Chris Collman -

Ralph, Thanks for the heads up.   I think I will put links to the most current.  Unless of course somebody can figure out the translocation feature that will move across different mediawiki's.  

I can not figure out if this is a plus or minus,  now we are 3 times as noticable as we were in 2006!

Trivia question of the day:  Who or what is the user "Tsala" ?  Is it some sort of acrynoymn?  Alot of rollbacks seem to point to that editor smile

Best  Chris

Average of ratings: -
In reply to ben reynolds

Re: Moodle documentation: Quick explaination of MoodleDocs verison migration

by Chris Collman -

I have been picking away at file picker, just the big stuff and basics.  Trying to figure out how it works, think some recent conribs by others have helped me.   But how to make it simple for the bald headed people in the world smile

We will be live in 2 weeks with one of our 2.1 Moodle servers.  So I guess I better figure it out quick.  

FYI:  I jump off thec cliff and swim with the sharks when I document. I tend to initially ignore forums, especially when the MoodleDoc page is almost blank.  I spend lots of time beating my head against demo.moodle.net or my localhost.  

On the other hand, this is not my style when it comes to "my" 3 new webservers and 2.1 moodles.  No code tweaks, it must be done via the moodle interface.

Good luck with your 2.1 and thanks for kind words.   It is all about us.

Chris

Average of ratings: -