Moodle in English: Moodle documentation: Update on Moodle 2.0 Docs

An update.

Docs 2 are getting ready quietly in the background http://docs2.moodle.org/ and we will very soon invite contributors from Moodle community to improve them.

You may notice a few changes:

Docs 2 is a separate wiki from the current Moodle Docs.

There are no more separate Admin and Teacher pages. They have been merged into User Docs. Developer Docs will be a separate wiki.

User Docs are now (visually) organised on the main page and accompanying Table of Contents like a manual. The pages listed are not the only pages in Docs, of course, but they are key pages that provide easier browsing, searching and editing of Docs.

Docs 2 are/will be Moodle 2.0 specific. The aim is to refer ONLY to items in Moodle 2.0 and disregard documentation about options in previous versions. For this purpose, many pages will need to be 'cleaned up' and a few new ones created. To make this task easier for contributors, we have scoured the existing Docs and provided a list of (useful) existing pages and what needs to be done to bring them up to Docs 2 standard.

We have changed a number of templates (boxes on the right hand side of articles), which now form the structure you see on the Main Page and Table of Contents.

A number of templates have been standardised. For example, all activities have the following template:

[Activity] settings - Everything related to BEFORE the activity is open to participants. First steps of creation and equivalent of clicking 'edit settings' (including permissions).
Building [Activity] - (Database, Lesson, Quiz, Feedback only). Everything related to building the activity AFTER the initial setup and BEFORE it is opened to participants.
Using [Activity] - Everything AFTER the activity is open to participants. Things like (if available) viewing, posting, grading, results, analysis, reports, good practices, creative uses, examples, pedagogical implications etc.
[Activity] FAQ - self-explanatory...

Existing pages have been preserved as much as possible to maintain links and keep the history of contributions. Some have been moved and redirected appropriately.

Still to do:

- Complete inserting templates on all related/useful pages and adjust instructions to editors accordingly.

- Improve the look of Main Page (only temporary, but gives you an idea...).

- Check (and change if necessary) the page links in Moodle to appropriate Moodle Docs.

- Create/re-organise/clean up the content of pages (all activities and resources plus a few clearly missing pages pages a priority)

- (Re)categorise pages related to a particular activity (resource, feature...)

We are hoping to start testing new Docs (particularly the links pages in Moodle itself) by mid June but will be opening them to contributors to create/clean-up content shortly. Will announce!

Each major Moodle version will have its own Docs (2.0, 2.1 ...), which will be a clone of the previous version but adjusted for things new and perhaps obsolete in the current version. Depending on the version, Moodle itself will point to the appropriate version of Docs.

I hope this sheds some light on the progress of the project.

Regards
Tomaz

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Thursday, 26 May 2011, 11:31 PM

Wow.

I noticed just a little bug, and the user views (5,000,000 plus) Whew!!

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Helen Foster - Friday, 27 May 2011, 5:47 PM

Thanks Derek, as Tomaz mentions, the main page is due for major improvements, but in the meantime the block title has been fixed.

The huge number of page views is due to the wiki being a copy of our existing Moodle Docs, which is clearly well-used!

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Ralf Hilgenstock - Friday, 27 May 2011, 7:59 PM

Hello Tomaz and Helen

thanks for your great work to preapre the new documentation concept.

Last Friday We had a one day meeting with German translation team and docs translation team. This team is keen to start the German pages as you know. Gisela is discussing details with you.

Here some issues from me:

If 2.1 will be published in July I suggest that 2.0. and 2.1 are one version. I think that in this short time only a few pages will be translated in 2.0 version. 2.0 versions link to the old wiki and not to a 2.0 site
If user come from the moodle system documentation link to the docs they get direct access to bvery detailled pages. How can we give them best advices to more general pages in the wiki.
Documentation is an ongoing process. If a page is not available in version 2.1, but in 2.2 and a user comes from a 2.1 system how did he get the information that the page is available/translated in next version? Or from the other side: Translators will work in the actual version: should they update/copy pages to elder versions?

I don't know if there are answers to these questions. May be ist not possible to solve all ideas.

Average of ratings: Useful (1)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Mary Cooch - Friday, 27 May 2011, 8:13 PM

Thanks from me too. This is a massive undertaking and will be really beneficial to the community (I was going to say "when it is finished" ...but then..it will never be finished!)

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Ralf Hilgenstock - Saturday, 28 May 2011, 3:05 AM

Hi Tomaz

two small problems in docs.

Ordering should be alphabetical and one module is missing. See Screenshot.

Average of ratings: Useful (1)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Tomaz Lasic - Saturday, 28 May 2011, 6:39 AM

Hi all

Reply to Ralf.

Fixed the missing 'Choice' module, done.

Re alphabetical order - virtually none of the content has been actually edited yet (I have only provided notes/guidelines/suggestions [example] for editors) and I imagine there wil be many things like you have just spotted (and thank you for it :D). It's a wiki and it's a living, growing thing (never finished, yes Mary).

Re: If 2.1 will be published in July I suggest that 2.0. and 2.1 are one version. I think that in this short time only a few pages will be translated in 2.0 version. 2.0 versions link to the old wiki and not to a 2.0 site

Yes, 2.1 will point to 2.0 Docs (that means 2.0 and 2.1 Docs will be the same thing, cloning and adjusting from 2.2 onwards).

Re: If user come from the moodle system documentation link to the docs they get direct access to bvery detailled pages. How can we give them best advices to more general pages in the wiki.

By way of templates and better navigation on screen (talking about the interface with Martin and Helen next week).

Re: Documentation is an ongoing process. If a page is not available in version 2.1, but in 2.2 and a user comes from a 2.1 system how did he get the information that the page is available/translated in next version? Or from the other side: Translators will work in the actual version: should they update/copy pages to elder versions?

Moodle 2.1 will automatically point to 2.1(2.0) Docs, Moodle 2.2 will automatically point to 2.2 Docs. The user will also be able to see Docs for previous versions but they will have to manually go there (eg. a 2.2 user whose Moodle is pointing directly to 2.2 pages will be able to go manually to Docs 2.0 for whatever the reason). We will ensure that people know exactly WHICH version of Docs they are viewing/editing.

Will provide more detail on re-direction from any missing pages, just need to check a few details with Martin and Jordan to make sure I provide you with accurate information.

Hope this sheds some light, thank you (all) for some top hawk-eye work already

Tomaz

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Martin Dougiamas - Thursday, 2 June 2011, 10:50 AM

Just a HEADS UP, the docs are being migrated to all the new URLs today and so everything will be offline for a while. See you on the other side (where a lot of work still waits!)

A correction from above, there will be 2.1 docs cloned from the 2.0 at some point after the 2.0 docs have settled down a bit.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Friday, 3 June 2011, 12:07 PM

Well done guys. I'm stuck in a transit hotel for 36 hours and have no English TV to watch except Martha Stewart so I'm having just a little look around here. Clicked on a lot of links and looking good.

A few philosophical comments follow.

I'd have chosen a different set of top level divisions, but hey, so would everyone of us. Basically, they are looking good. Tomaz, make sure you have a good weekend!! Some comments from a personal point of view follow. I'm just not quite ready to click the editing button yet though.

I tend to think of these levels:

Server functions
Site functions
Course admin functions
Teaching activities
User (ie student) activities.

A. 'Teaching activities' topic is slightly hidden at the top level behind the Learning and evaluation http://docs.moodle.org/20/en/Learning_and_evaluation_tools link.

I just don't like Headings being links, (too much blue). People can often just NOT click on them.
My bias is for teaching and learning in the terminology NOT evaluation
I'd probably have Overview as the top link, and make the heading unclickable.

B. There is no clear BIG link to the topic "New to Moodle, start here" It is "hidden" in the link to "About Moodle" ie http://docs.moodle.org/20/en/About_Moodle. We need a page to send people in the forums who say "I'm new to Moodle, please help me, thanks"

I think this needs some more chatty text like this: to see more about setting up a server (links), for teaching with Moodle (links), for advocacy about Moodle (links) - kind of chatty. But not too much. My model was Wordpress (eg http://codex.wordpress.org/New_To_WordPress_-_Where_to_Start) but over the past year they have tried to put extra stuff in and it's lost it's sharpness.
Much more like the style of http://docs.moodle.org/20/en/Learning_and_evaluation_tools

C. I'd like two other links someting like this:

"Teaching with Moodle" (in Learning section)
"Course design with Moodle" (in managing section)

Almost like philosophical and "good practice" magazine article type style. But these could be controversial (everyone has opinons!!), and there are books, blog posts etc

C. I'd like to soften http://docs.moodle.org/20/en/Learning_and_evaluation_tools to be a bit more about

"Enhancing collaboration with . ."
"encouraging interaction"
"Creating activities for students with Moodle tools"
"Saving time" With more use of the tiers teaching and learning.

D. Randoms

http://docs.moodle.org/20/en/Future What about a roadmap for non-developers?
Whimsical suggestion: what about an FAQ for the top 10 questions to make Eleana, the Marys, Helen, Frank, Sam, Tomaz, Tim's (etc) life just a little easier (File upload size, file system, templates, upgrading to Moodle2, ForumNG, moodle hosting
Media is going to need some work. http://docs.moodle.org/20/en/Working_with_media I've contributed to some of the detritus in the old pages.
This is where I may start.
File bank? http://docs.moodle.org/20/en/File_bank is this an "official" term? Random musing: files stored with the activity/resource are NOT really a repository. Everything else is maybe?

Enough. I have made my first edits as well (not game to start content, just formating)

And also, maybe 20 clicks on other pages that are looking good, 20 clicks on pages that need tweaking. Still a lot of work!! Tomaz, don't forget the weekend.

And you guys in other languages, good luck also.

-Derek

Average of ratings: Useful (2)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Tomaz Lasic - Tuesday, 7 June 2011, 10:58 AM

Been off grid for a few days (is that the weekend you refer to ) and just seen your thoughtful reply. Cheers.

Re Martha Stewart: Your poor sod ...

Re 'think of these levels': Fair enough but how long is a piece of string... This broad organisation/major topics is probably there to stay (should have seen the big sheet of paper I had EVERYTHING on [yes, paper!] for months). Not saying nothing will change but we do need to be circumspect about chopping/changing too much.

Re: 'Teaching activities' hidden (and New to Moodle , start here): 100% agree, let's make it happen.

Re 'teaching and learning in the terminology NOT evaluation': Mine too but had to slot those somewhere without fragmenting too much. That 'piece of string' again ...

Re: 'more chatty text' (especially for first timers): 100% agree, care to chip in anytime. I will be adding a lot of that stuff over the next few weeks. Chatty? Me? Nah

Re: "Teaching with Moodle" , "Course design with Moodle" , mag style article(s) ... - Agree!!! Large topics each though, probably re-invigorate that course http://moodle.org/educators for something like that too, not to forget Moodle Buzz too.

Personally I have always been a bit suspect of 'best way to teach with Moodle' and 'best way to design a course' materials. Helpful, no doubt at all (!!), but people tend to see it as 'gospel' and limit their own creativity, don't adjust for their own context. Basic probably enough, then - dive in, moodle away and join the conversation!

To extend your philosophical note, I have forever wrestled with a question 'what is 'good' education' and I'd never like to see a comprehensive universal answer.

Re soften the Learning & evaluation tools...: +1 ! Must have been that guy who looked over my shoulder on the train while I was typing it :D Willl work on it, remind me if I don't please.

Re Randoms:

Roadmap for non-devs: a non-geek, easy to get ... getting boring in how we agree!
What about something like 'Current Top 10 FAQ', rotating and based on the most 'burning' issues in the Moodle community ATM? That'd be VERY useful.
Media: Oh yes, that baby needs work. Can't believe we have not had an easy to get, 'organising' page on video in Moodle for example. Welcome to edit!
File bank? Will check (again), not to be lost in jargon.

Hope this is more interesting than watching Martha.

Thanks for your thoughts, edits and encouragement. Appreciated.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Frank Ralf - Tuesday, 7 June 2011, 3:14 PM

JFTR

See also Moodle 2.0 , Page naming and sort a progress report and Moodle docs filter.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Tomaz Lasic - Wednesday, 8 June 2011, 9:59 AM

Thanks for that Frank. An ongoing conversation.

As Colin Fraser rightfully pointed out in that thread, we need to avoid "...the "Microsoft methodology" for documentation. Make it too complex for neophytes to read properly. Anyone remember Borland's TurboPascal help files? Make it detailed, but couch everything in language that few will understand and follow. I found it easier to put the books on the shelf for six months so I could learn what questions to ask and have a good chance of understanding the answers."

A few points from my end on the rationale for the design of Docs 2 (an overlap with my first post in this thread):

- Easi(er) to navigate, search AND browse (ie. the person doesn't get lost in exploring a myriad of links [as exciting as it may sound to some people...], you can always easily see the whole thing (or at least main parts of) via Table of Contents plus have the templates that accompany/expand what is written on the page.

- Lose Admin/Teacher distinction but instead organise all as User Docs in main 'chunks' (the six big areas 'About/Getting/Site/Course/Tools/Content); Site - aimed primarily at Admin there, Course at teachers, the rest more general, overlapping.

- Create and maintain a basic structure via templates (doesn't prevent people from adding pages) - make it look more like a manual

- Standardise templates for activities and resources - as a user would use/need them in stages BEFORE opening to students (settings/creation stage) and AFTER opening to students (using). So many pages are/were a mix of settings, tips, pedagogy, types etc. Having the same type of template for all activities makes it easier for people to find what they are after, faster (manual, again)

- Have just a few 'launchpad' pages (mostly for the main sections of Docs; first and second 'level' on Table of Contents) that simply point the reader in the right direction, example. Too many and maintenance becomes and issue, too few and people get lost.

Currently, I'm tidying up/re-doing the templates (which will also include a parent template, had a meeting with Martin about that yesterday, see example) and creating/editing some of the most 'critical' content ATM, example (talk page).

I will post a list of pages that IMO need the most and earliest of our attention to either bring them up to Moodle 2, check for accuracy or start alltogether.

Average of ratings: Useful (1)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Wednesday, 8 June 2011, 10:20 AM

OK everybody.

Dumb question time. Why is only one person really working on the Moodle 2.0 docs? (Xiaowan Dong)

Busyness? Lack of internet access? Overwhelmed at where to start? Too busy coding for 2.1? Watching Youtube videos on Planking? At the beach?

-Derek

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Mary Cooch - Wednesday, 8 June 2011, 1:14 PM

Or too shy? That's my problem (well, yes apart from having a busy job in the Real World!) I'm always wary of adding to stuff in case I am encroaching on someone else's pet territory and I am confused since I saw one of Martin's talks where he said that the docs were being rationalised and they would have specific people editing them rather than the whole world and his brother which had led to them being unwieldy

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Wednesday, 8 June 2011, 2:21 PM

Too shy Mary?! You must be having us on.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Frank Ralf - Wednesday, 8 June 2011, 2:33 PM

Hi Mary,

Having written some great books on Moodle should qualify for contributing to Moodle Docs

And after all, it's a wiki so no one can really do harm there.

Frank

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Helen Foster - Thursday, 9 June 2011, 1:18 AM

I am confused since I saw one of Martin's talks where he said that the docs were being rationalised and they would have specific people editing them...

There is definitely a misunderstanding here. Everyone is welcome to contribute to the Moodle 2.0 documentation, the same as it's always been. Perhaps Martin was referring to Tomaz's reorganisation work which is now complete (mostly!)

Mary, please don't feel you're encroaching on anyone's territory. Feel free to add/edit documentation anywhere in the wiki. You can always edit your profile and change your name to moodle fairy if you'd be happier writing under a pen name.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Tomaz Lasic - Thursday, 9 June 2011, 11:08 AM

Mary (and everyone else...), I can only echo Helen here - PLEASE DO contribute.

Docs are OURS as in Moodle community, not Helen's, Martin's or mine for that matter ... how anti-Moodle would that be!

Helen and I are just nudging, shaping, managing things a bit. Sometimes this does involve making a call or two that perhaps not everyone would agree with (recipe for disaster if we go down that path) but I assure you we have the larger community in mind at all times and we are immensely grateful for all the work Docs editors have done, do and will continue to put into our 'Moodlepedia' of Docs.

Re 'pet territories' and stopping things go unwieldy. You have a point but assigning articles to certain people according to their 'pet areas' opens up a new set of problems. Inclusivity can be (well, is!) a bit messy but still the operating principle behind a wiki really. We'll just...consult, negotiate and understand (and delete, move, argue a bit, of course As long as it is done in good faith, we can all sleep well.)

So ... fire away !

Oh, I am about to open up a new thread on Most Wanted Pages - Docs 2, see the list there, including the priorities.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Visvanath Ratnaweera - Thursday, 9 June 2011, 7:08 PM

Hi all

Though this "shyness" coming from Mary sounds peculiar

there is a message behnd it. In a couple of occasions I wasn't sure whether my twopenn'orth would help or irritate the author. As a solution I tried placing a note in the "talk" section [1, 2] but haven't received any response. So without understanding the culture aka "work flow" at docs.moodle.org I was hesitant. "Please do change" sounds good but not practicable, imagine what happens if I change the whole table of content?

In the case of the Performance FAQ [3] I seem to be on the other side. Very few have changed anything in that, although I've left many stubs.

The tool wiki is one thing, the understanding is something different. I must have missed previous discussions where this understanding took place. I appreciate if somebody could post those pointers.

Apart from the "understanding" part there are practical questions. My immediate ones I've posted in the othe subthread [4], am still hoping for clarifications there.

[1] http://docs.moodle.org/20/en/Talk:Moodle.org_forums_Code_of_Conduct#feedback_or_rate_and_solved
[2] http://docs.moodle.org/20/en/Talk:Server_cluster
[3] http://docs.moodle.org/20/en/Performance_FAQ
[4] http://moodle.org/mod/forum/discuss.php?d=176065#p776437

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Lisa Kidder - Wednesday, 8 June 2011, 10:14 PM

We here at ISU have been working on documentation, but I've been waiting until the migration and templates that Tomaz mentions were out. I didn't want to undo anything anyone was planning.

Looks like things are starting to settle down so I should be putting in the information we've been drafting soon.

I only wish I had the excuse of being at the beach

Lisa

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Helen Foster - Thursday, 9 June 2011, 1:37 AM

Hi Lisa,

Now is the perfect time for you to add documentation. Thanks in advance!

PS Here's a nice beach pic (from http://en.wikipedia.org/wiki/Beach ) seeing as you can't get there in person.

Attachment 300px-Man_owar_cove_near_lulworth_dorset_arp.jpg

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Thursday, 9 June 2011, 10:56 AM

To extend your philosophical note, I have forever wrestled with a question 'what is 'good' education' and I'd never like to see a comprehensive universal answer - Tomaz

Point taken, but I've got no problem with writing about 'Good" education. It's the word 'best' (as in best practice) I dislike.

-Derek

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Visvanath Ratnaweera - Wednesday, 8 June 2011, 5:35 PM

Hi all

I know, I'm late in understanding what's happening. I noticed that the link http://docs.moodle.org/en/index.php?title=Special:Search&go=Go for the "Moodle documentation search box" which I've used in the introduction to the "Hardware and Performance" forum http://moodle.org/mod/forum/view.php?id=596 is broken. A little bit of navigation showed me that it has to be either http://docs.moodle.org/19/en/index.php?title=Special:Search&go=Go or http://docs.moodle.org/20/en/index.php?title=Special:Search&go=Go

Now my questions:
- What is the prescribed way of handling this: Have two links, one for 1.9 and one for 2.0?
- How do you go ahead when 2.1 is availabe, I can remember June or July was mentioned.

In fact all the links http://docs.moode.org/en/Something including http://docs.moodle.org jump to http://docs.moodle.org/20/en/Something Is this intentional? Earlier http://docs2.moodle.org was mentioned in some other thread. Is it dropped?

Another thing. Pages like http://docs.moodle.org/en/Performance have doubled. The original is automatically taken to http://docs.moodle.org/20/en/Performance whereas an almost identical copy remained as http://docs.moodle.org/19/en/Performance In future are these two documents to be maintained seperately?

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Martin Vögeli - Thursday, 16 June 2011, 4:39 PM

Hi folks

Like Visvanath I wonder if it's a good idea to duplicate information. He already mentioned some of the issues which might arise. In addition, I wonder where search engines will take me in the future when I'm in need of help? Version 1.9, 2.0, 2.1...

Or at times I answer other people's questions. In the past I sent them a link to the adequate Moodle Docs page. In the future I have to know the exact Moodle version in order to help. I'd definitively prefer one Moodle Docs for the various versions.

But that's just my two cents

Best whishes, Martin

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Martin Dougiamas - Thursday, 16 June 2011, 6:05 PM

I think the issue is that more and more of docs are becoming version-specific, even things like performance.

As time goes on cramming that information into one wiki is much worse than clear, separate user manuals for each version, where the search only covers what you need.

This page shows the wiki structure: http://docs.moodle.org/overview/

Average of ratings: Useful (1)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Martin Vögeli - Thursday, 16 June 2011, 11:11 PM

Wow, thx for your speedy and informative reply!

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Visvanath Ratnaweera - Sunday, 19 June 2011, 3:49 AM

Hi Tomaz and Martin

I beg to differ.

It so obvious to me that the version dependency of the documentation belongs to the last leg of the hierarchy, I can't think of a line of argument! May be it is easier to show the problems in taking it to the top most level, in effect starting too seperate documentations.

- Let's stay with the example mentioned: http://docs.moodle.org/19/en/Performance and http://docs.moodle.org/20/en/Performance look at the content and judge for yourself how much those two are going to differ. I would say 5 - 10% max. The biggest problem is not those 5 - 10% but the rest, the duplicated part. Wenn somebody starts polishing one version, that person naturally sees other parts of the documentation which need corrections. But those corrections will not be "back ported" to the other version! As time goes on, corrections are made in only one, or the same information will be formulated differently, etc.

- A typical discussion in support forums contain links to the documentaion, at least that makes the major part of my posts. E.g. http://moodle.org/mod/forum/discuss.php?d=175438 I meant http://docs.moodle.org/en/Administrator_documentation#Installation_.26_Upgrading, without the version, because the OP doesn't mention one. But my link jumps to http://docs.moodle.org/20/en/Administrator_documentation#Installation_.26_Upgrading , to version 2.0. Now if the OP was trying to install 1.9 his first impression will be, that I've posted the wrong link.

- Then there are those absurd pages: If it is very important, one can organize differtent user groups for different versions http://docs.moodle.org/19/en/Moodle_user_groups and http://docs.moodle.org/19/en/Moodle_user_groups but different code of conducts for users of different versions, http://docs.moodle.org/19/en/Moodle.org_forums_Code_of_Conduct and http://docs.moodle.org/20/en/Moodle.org_forums_Code_of_Conduct , are unlikely, am I right?

- Once the version 2.1 comes out soon, the scale of the probs will be tripled.

There may be other reasons, but the most important one is the one at the top.

This version dependency is nothing new. Any book on a computer application which has two or more versions in use has the same problem. The typical book solution is to indent those paras with some icon or a pictogramme. I've seen an ingenious solution for a related but more complicated problem in the preprocessing system for web "Website Meta Language", see http://thewml.org/example/

I'm not saying that the documenters of Moodle.org has to undergo such treatment. But I'm sure that the expert webmasters we have, can provide a template to mark version dependencies so that the wiki will get it nicely formatted including the corr. pictogramme.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Sunday, 19 June 2011, 7:03 AM

Visvanath

You have some good points of course.

Frank Ralf gave us a short lesson in transclusion: http://docs.moodle.org/20/en/MoodleDocs:Transclusion

http://docs.moodle.org/20/en/User:Frank_Ralf/Subpage_transclusion

http://moodle.org/mod/forum/discuss.php?d=169322&parent=742919

The Moodle "core" docs could be transcluded - like roadmap, codes of conduct etc.

Thoughts?

I just want to get this thing done and dusted so people can move on to other things like research and Moodle 2.2

-Derek

Average of ratings: Useful (1)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Frank Ralf - Sunday, 19 June 2011, 11:45 PM

Hi Derek,

Thanks for the reminder

Transclusion might indeed be a viable way to go for avoiding duplication of content.

One example in action is NanoGong/Converting_to_Moodle_2.0 which actually is transcluded from User:Frank_Ralf/NanoGong which you will see when you edit a section of that page.

Cheers,
Frank

Average of ratings: Useful (1)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Martin Dougiamas - Monday, 20 June 2011, 4:39 PM

You need to take these case-by-case I think.

Please remember that the main docs are now focussed on being user docs, about the Moodle software itself.

1) Performance is version-specific. They will vary more and more. It makes sense to have versioned pages. And yes there will be common stuff ... people need to start being aware of which version they are editing and remember to update the latest as well (if they aren't already doing so).

2) These sort of pages (installation/upgrades) are extremely version-specific, and also good candidates to add specific links to other versions of the page to help people get to the right place.

3) Code of conduct, and anything else like that which is not part of the user documentation for Moodle itself should go to other places. Policy stuff can move straight on moodle.org as a normal uneditable web page. The list of user groups could go into a Moodle wiki on moodle.org, or a database. Anything development-related must move to the development wiki (that includes versions, release notes and roadmaps etc).

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Frank Ralf - Saturday, 2 July 2011, 12:37 AM

@ 3)
I think it's difficult to draw the line between what is development-related and what isn't.

For example the following is my "mantra" when giving advice in the Themes forum (which I would not deem to be development-related):

"CSS FAQ and Themes FAQ are good starting points for learning more about CSS and theming. And use Firebug for analyzing and modifying a webpage's CSS."

* Firebug used to be in the Developer namespace but hasn't been moved to the development docs (yet)
* Themes FAQ should be part of the normal documentation (or the one for admins), it contains many answers to regularly posted questions in the Themes forum.
* CSS FAQ contains general information on CSS aimed at non-developers.

IMHO the development documentation should only contain information for "hard core" developers, i.e. programmers. I wouldn't count theme modifications under development.

Frank

Average of ratings: Useful (1)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Frank Ralf - Thursday, 28 July 2011, 6:08 PM

Just some more points to consider:

* Themes is part of the user/admin documentation, why not Themes FAQ?

* Special:PopularPages could give some hints which pages are most popular and as such probably read by "the general public" instead of only coders.

Average of ratings: Useful (1)

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Helen Foster - Friday, 11 November 2011, 3:22 PM

Thanks Frank, I've followed your suggestion and moved Themes FAQ back to the user docs.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Robert Brenstein - Monday, 27 June 2011, 4:46 PM

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Sunday, 12 June 2011, 1:27 PM

I've linked/tweaked a couple of pages on plugins etc. Can someone who knows update the top of http://docs.moodle.org/20/en/Category:Contributed_code to use the word GIT in the right places?

-Derek

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Tim Hunt - Sunday, 12 June 2011, 11:29 PM

I just gave it a go, but am not very happy with what I wrote. What I wrote is factually accurate, but the wording could be improved, so please feel free to hack around with what I wrote.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Martin Dougiamas - Thursday, 16 June 2011, 5:53 PM

Just an update on Docs ... I plan to be personally getting stuck into these for the next week or two 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.

The trouble is that a lot of changes are still incomplete but that's all in people's heads, and it's not obvious from looking at docs as they are now. Also there are some important pages about Moodle functions that are just factually wrong, which I also need to work on.

I hope everything is much clearer soon!

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Monday, 27 June 2011, 7:07 AM

Just curious:

Why has the roadmap been moved to dev?

http://docs.moodle.org/20/en/Roadmap

I think it belongs in the core help docs.

-Derek

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Derek Chirnside - Saturday, 2 July 2011, 7:59 AM

I realise all you guys have been busy with 2.1 and it is a bit sad replying to your own post.

What is the rationale for moving pages about upgrading (which is admin, not dev) to dev? http://docs.moodle.org/20/en/Upgrading_to_Moodle_2.1

This goes against the plan in the original post from Tomaz: http://moodle.org/mod/forum/discuss.php?d=176065 Two streams: dev and others (incl admin and teachers)

I know there needs to be a line drawn somewhere. But I saw a post somewhere recently suggesting: keep dev for coders and developers, not admins.

-Derek

Average of ratings: -

Re: Upgrading docs

by Helen Foster - Thursday, 10 November 2011, 9:15 PM

Hi Derek,

You're right about the upgrading docs. We realised it was a mistake moving them to the dev wiki and so they have been moved back.

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Mike Algozzine - Thursday, 30 June 2011, 4:32 AM

We just noticed that docs.moodle.org/19/en_us links are redirecting to docs.moodle.org/20/en links. Shouldn't they redirect to docs.moodle.org/19/en instead?

Average of ratings: -

Re: Moodle documentation: Update on Moodle 2.0 Docs

by Helen Foster - Thursday, 30 June 2011, 2:55 PM

Mike, yes docs.moodle.org/19/en_us links should redirect to docs.moodle.org/19/en. I've reopened MDLSITE-1296 so the problem can be fixed.

Average of ratings: -