Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Chris Collman -
Number of replies: 12
Picture of Documentation writers
Hi,

I would like some feedback via talk:page on new pages I created or here, concerning page names and page formats around the Moodle 2.0 release.

I got the Preview version of Moodle 2.0 up and running and decided to look at how documentation is going to work with the new UI navigation/menu system. I started with Settings block (created new page) realized that Site administration menu 2.0 (new page, comments appreciated here) window had some important differences and then focused upon the new Plugins>Activity modules>Lesson so created a Lesson settings (new page, comments appreciated here) and finally looked at the new Updating a Lesson (new page, perhaps MoodleDoc page name issue) window which was also different.

I could have gotten sidetracked with Tracker issues with page formats and other minor stuff, but decided to ignore them for the moment. Those new pages amounts to more than a few mornings of work smile

The new navigation system thinks a bit differently than the old, yet some windows have the same name. For me this creates a documentation issue if the functions are radically different between 1.9 and 2.0. Then there are new windows, with sometimes simple names like "Lesson".

The word "settings" definitely has a contextual basis. For example, when in a Lesson a teacher will see in the "Settings" block a heading called "Lesson administration" and under that a link to "Settings" (the Updating a lesson window, with the Adding/Editing a lesson as a help page link. Yet when logged in as Admin and in a Lesson, you see the teacher settings and then below the site administration link where you can dig down and find the site "Lesson". I think of this as settings but I guess it could be called "Lesson defaults".

I am sure the same thing will be true of other activities, resources and blocks.

I am rambling so will stop, please leave some comments or send me a message.

Best to all , Chris

(Edited by Helen Foster to fix Moodle Docs links - original submission Monday, 10 May 2010, 04:26 PM)

Average of ratings: -
In reply to Chris Collman

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

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

Thanks for starting to think about Moodle 2.0 documentation. You're way ahead of me!

Regarding page naming, I suggest we leave it for a while, as things in 2.0 can still change. I'm still getting used to a settings link in the settings block. wink

Regarding 2.0 documentation generally, I wonder whether it's necessary to create new pages for existing features or whether a version template can be used like before?
Average of ratings: -
In reply to Helen Foster

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Colin Fraser -
Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Testers
Helen asks "Regarding 2.0 documentation generally, I wonder whether it's necessary to create new pages for existing features or whether a version template can be used like before?"

I too have considered this question, but perhaps from a more simplistic angle. It is my thought that to simply tack on another section to existing pages may serve to confuse issues. I suggest that an entirely new block of pages that are unrelated in anyway to existing Moodle documentation except via the Main Page - Moodle Docs, be developed.

I would advance this because of the ease at which version specific information can be confused as it is. From what I have seen of Moodle 2.0, there is going to have to be a major rewrite of a lot of the documentation, plus a whole new set of images for even simple aspects of admin and Teacher documentation, let alone trying to explain the vastly simplified installation process. (And I have not had time to do much more than scratch the surface.)

While a lot of people are good with documents, too many people ( and I am, far too often, no exception here..thoughtful) use the older adage, "if all else fails, read the instructions." When it all fails, a "quick read" of a help file could make it too easy to not discern which version the documentation was alluding to. Frustration levels rise, and eventually a surrender - to not return to whatever it was causing a problem i.e. drop Moodle altogether.

Another aspect of this is 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.

Unfortunately, who has time to do that anymore?



Average of ratings: -
In reply to Colin Fraser

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Chris Collman -
Picture of Documentation writers
MoodleDocs has faced this kind of transition before. I think the difference here is the breadth and depth of the changes to the interface.

For example the Settings block looks and functions differently. Even if you just consider the former Site administration block, as a subset, it has some major new parts, it's own groupings of functions have been reorganized and the navigation is different.

I think in some MoodleDoc pages, we are going to have to immediate provide a link to the 2.0 page, or to the "legacy" page. Perhaps we can do this with a template that uses variables but has a standard look of something like stub or the Moodle Version? There are lots of different ways this is done in Wikipedia. we need a KISS method for me smile

Chris

Average of ratings: -
In reply to Chris Collman

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Frank Ralf -
Hi Chris,

I agree that we need a clean solution as soon as possible.

A recent issue was mentioned at Development talk:Local customisation where the whole 1.9 documentation was wiped in favor of the new 2.0 one and had to be resurrected from the history.

What about creating a new namespace for Moodle 2.0 so Development:Local customisation would become Development 2.0:Local customisation. That would leave the page names unaltered.

Cheers,
Frank
Average of ratings: -
In reply to Frank Ralf

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Chris Collman -
Picture of Documentation writers
Hi Frank,
Thanks for the link. There will be some active legacy systems that will be still be unchanged in say, 5 years from now. Not an entirely random number smile

Then there are always subpages, which could become something like a cache or even series of caches. Lesson module\Pre2.0 Lesson module or Lesson module\1.9 Lesson module, ..\1.8 Lesson module.

The cache-subpage idea seems awkward to me, I like the name space concept better. We could train people to customize their MoodleDocs searches/view, so the default is either the 1.x or 2.x name space. Thus when 3.x comes along we will be all set.

Chris


Average of ratings: -
In reply to Chris Collman

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Colin Fraser -
Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Testers
That is an interesting point Chris, future planning..big grin . Keep is as simple and as relevant to the actual need as opposed to what is easiest for the documentation providers. Besides, if we, as a community, get used to thinking about what the ordinary users really need then it will make using Moodle Docs a pleasurable experience rather than the nightmare of cross-referencing that MS Knowledge Base has become, as an example.

The point you make regarding what may happen in the future, is actually quite incredible when you think about it a bit. What we, and I use the term "we" deliberately in as much as I mean everyone from Alan Aardvark to Ziggy Zzaleki, anyone who has contributed a comma or two once to a Moodle Doc, is really creating a series of practices that can be adapted by some, as yet un-named players, at some unspecified time in the future. A tradition! Wow, to think - my name in history - what an appalling - (erm - um - appealing, yes that is a better word) appealing thought... clown

Average of ratings: -
In reply to Frank Ralf

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Frank Ralf -
Created an official tracker issue at MDLSITE-1134 to move things forward.
Average of ratings: -
In reply to Frank Ralf

Re: Moodle 2.0 documentation

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

Frank, thanks for your suggestion to create a separate namespace for Moodle 2.0. However, I see a couple of disadvantages in organising the documentation in this way:

  • Pages in the new namespace won't appear in searches unless people select the namespace in an advanced search or change things in their preferences
  • Unless categorised in a particular way, pages in a 2.0 namespace would be listed under "2" on category pages, rather than in alphabetical order according to the title (just as all the pages in http://docs.moodle.org/en/Category:Obsolete_Design are listed under "O")

I think that the context-sensitive 'Moodle Docs for this page' links within Moodle are the best way of helping people find the documentation they need.

New features in Moodle 2.0, such as Repositories and Portfolios, can have new documentation pages with the 2.0 template and a note that the feature is in 2.0 onwards.

With improvements to existing features we can do the same as for the gradebook improvements in 1.9 i.e. have a highlighted note at the top of the page directing people to documentation for other versions, for example Course backup.

What does everyone think? Is this a clean and simple solution, or can we make things even simpler?

Average of ratings: Useful (1)
In reply to Helen Foster

Re: Moodle 2.0 documentation

by Frank Ralf -
Hi Helen,

Thanks for your feedback! Both issues you mention can be solved.

a) You can add to the namespaces searched by default, see http://www.mediawiki.org/wiki/Manual:$wgNamespacesToBeSearchedDefault

b) You can use a sort key for keeping the correct sort order like we already do with Category:Developer, see http://docs.moodle.org/en/Template:CategoryDeveloper

But I admit that this might be too complex. So a solution based on categories and templates might indeed be the more flexible and viable solution.

Cheers,
Frank
Average of ratings: -
In reply to Chris Collman

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Chris Collman -
Picture of Documentation writers
Hi Helen and all,
Will continue the discussion here instead of the talk pages in MoodleDocs.

Moodle 2.0 Settings block is different. For example, I assume that manager in QA is not an administrator, and this impacts what this block shows.

The "Site administration" page/path has many new features in 2.0 and ways of thinking. The most obvious to me is Plugins , which generally referred to contributed codes in earlier Moodle versions. Doing a translation when we move to 1.9 is going to be interesting. Perhaps my site administration 2.0 could be Development: .

Digging down, >Activities modules>Manage activities is the same as Activity modules administration. However, below this in 2.0 are the links called "Settings" which appear in the Manage activities screen, except they just give the activity name. These pages in MoodleDocs seemed to be called "_settings". I think we should use the opportunity to call them "_defaults". Set up a redirect page or a disamb page to direct MoodleDocs to either the "Adding/Editing_" or the "_ defaults" pages.

The word "settings" has too many contexts in Moodle. At least "defaults" gives a bit more specific context.

I did try the start of a translation to Moodle 2.0 in Adding/editing a lesson. Like site administration, the format of this page has changed by moving things around, to Lesson defaults and seemingly eliminating former "settings". I have not looked at other modules, so it maybe that Lesson is coming into line with a 1.9 Moodle way of organizing things smile

Gotta run to my paid job.

I understand that things will change smile That is why I am just following 1 or 2 paths down the Settings block, rather than doing one layer at a time.

Best Chris
Average of ratings: -
In reply to Chris Collman

Re: Moodle documentation: Moodle 2.0 , Page naming and sort a progress report

by Derek Chirnside -

I've thought about this also.  This is a simplistic suggestion.

Consider this page: http://docs.moodle.org/en/Category:Moodle_2.0

Can this be set up to show all the 2.0 pages which are NOT development:

Or maybe set up a Help 2 Category, and all the Documentation specific to 2 ge this tag.

-Derek

Average of ratings: -