Upgrade of Moodle docs and Ad-hoc reports page

Upgrade of Moodle docs and Ad-hoc reports page

by Randy Thornton -
Number of replies: 14
Picture of Documentation writers

All,

There was recently a major upgrade to Moodle Docs Mediawiki to version 1.3. This includes some major changes to the wiki syntax, which affected all the code on the Ad-hoc reports page.

I have taken it upon myself to fix all those and the page is now working again. There is a new syntax style for code and I think, at least, it looks a lot more readable than the old mediawiki style. The old syntax using "code" is gone and replaced by a new style using "syntaxhighlight" (see more on this at the Mediawiki page about it.)

Please let me know if there is any code there that remains broken. Feel free to fix it yourself of course ;)

Also, I have take this opportunity to add some new content to the page: I have added an introduction for new users which contains some basic information on the plugins, how some of the quirks of the queries on the page work (eg, what prefix_ means, dates and formatting, etc.) I have also added some pages at the end with some useful things like common constants, table aliases, variables, code snippets, etc.

I have added a section called "Suggestions for contributors." I hope people will agree me with me that these are useful suggestions. Most of these suggestions come from what I see in this forum over the years, where people trying to use the queries have issues with them arising from queries written for old versions of Moodle, or another dialect of SQL, and so forth.

Further cleaning up?

In particular, there are lots of old queries from Moodle 2.x days and even a few antiques from Moodle 1.9 days. These only cause frustration for new users of Moodle trying to use them. I think it is a reasonable expectation that on a page for Moodle 3.11, for example, that the queries there should work on Moodle 3.11.

Keep in mind that that this page is rolled over twice a year by Mary Cooch along with all the other Moodle docs pages at the time of each new release. If you wanted to find queries for Moodle 2.5, you can find them as those pages still exist out there. That's how to get queries written for older versions.

So, I would like to float the idea of whether it would be a good thing to remove old queries from this page. I'm not sure though if that is a good idea or exactly what "old queries" would mean. In many cases, it would be very hard to figure out who wrote a query and even then they may be long gone from the community and have no interest in reviewing old queries. Still, I think it would be useful to help reduce the issues for people use the page.

Thoughts on this?

Randy



Average of ratings: Useful (7)
In reply to Randy Thornton

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Randy Thornton -
Picture of Documentation writers
One more thing:

If anyone out there is up to date on how all the filters in Config Reports work, I have added a stub section for that at: https://docs.moodle.org/311/en/ad-hoc_contributed_reports#Filters.

Long ago, I did a small tutorial there on how the Date filters work. But, if anyone wants to add some real examples of how other filters work, that would be very useful for others.
Average of ratings: Useful (4)
In reply to Randy Thornton

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Séverin Terrier -
Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Testers Picture of Translators
Thanks Randy for all the improvments you made on this page. It looks nice and all needed information (about plugins, aliases...) is clearly written smile

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

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Randy Thornton -
Picture of Documentation writers
Thanks, Séverin. I appreciate that.

Many people use the pages who are not native speakers of English. So, I have tried to keep the explanations as clear as I can.
Average of ratings: -
In reply to Randy Thornton

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Séverin Terrier -
Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Testers Picture of Translators
You're right, and i'm the first concerned.

If i had time, it would be really useful if i could create a french version of this page, with all useful information (but perhaps pointing to the english one for the queries). But i doubt to have time for this before months (or years). Hope (but doubt) someone else can take care of that.

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

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Randy Thornton -
Picture of Documentation writers
I had thought about that as well. I was thinking to perhaps do a Spanish version, or to work with German Valero to do one, but for now I think having one that is clear and readable in English would be more important.

Most of the reports lack descriptions. Many of them are old and may not work in Moodle 3 properly anymore.

I have been focusing on reorganizing them and adding explanations for commonly asked questions. I was thinking of doing a tutorial for how to get started with using these, on another page perhaps.
Average of ratings: -
In reply to Randy Thornton

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Shirley Gregorczyk -
Picture of Particularly helpful Moodlers
I sincerely appreciate your excellent, update to information I frequently use- Thank you!
Kind Regards
Average of ratings: -
In reply to Randy Thornton

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Marcus Green -
Picture of Core developers Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers
"So, I would like to float the idea of whether it would be a good thing to remove old queries from this page."
Yes, Yes and Thrice yes (yes, yes yes).
Be bold I trust your judgement, it's a wiki people can always look at the history.
Average of ratings: Useful (2)
In reply to Marcus Green

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Randy Thornton -
Picture of Documentation writers
Thanks Marcus. I will take that as a yes!

I have long wanted to just wholesale remove those, since, exactly as you say, all the old pages are still there and any old query can be found.

I have moved all the queries that use the old logs into a section just for old logs. So, to delete them will be easy.
Average of ratings: Useful (1)
In reply to Marcus Green

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Randy Thornton -
Picture of Documentation writers
Okay, those are removed. Thanks so much for the encouragement, Marcus!

I just removed the whole section of ancient logs and added something to the Introduction on how the logs work and where to locate and find any pre 2.7 log queries. Honestly, anyone using old logs is either an expert with some interesting archive requirements or an unfortunate soul who really needs to upgrade their version.

I feel cleaner already ;)
Average of ratings: -
In reply to Randy Thornton

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Thomas Stanley-Jones -
Thank you! I had noticed the changes just recently on the 3.11 page and really liked it. It's great to hear that the old code has been taken out as well. Being new to the database side of Moodle it was difficult to sift through.
Average of ratings: -
In reply to Thomas Stanley-Jones

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Randy Thornton -
Picture of Documentation writers
Thomas,

Thanks. It's a lot easier to usesmile I do plan on continuing to round out some of the topics that I think could help others. Always feel free to contribute of course smile
Average of ratings: -
In reply to Randy Thornton

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Thomas Stanley-Jones -
Alright, I've just got myself setup to begin to contribute to the Ad-hoc pages. I'm running on Moodle 3.10 right now and I'm wondering where it would be best to contribute. I have a few questions and would appreciate some guidance.
- All the pages before 3.11 are old (without your major upgrade on the 3.11 page), is it worth doing any updating to those (syntax highlighting, old code removal, etc)?
- If I add some bits about filtering, templates, and useful reports, should I just add these to the 3.11 page? I'm not sure how much has changed between 3.10 and 3.11.

Also, is there a page that I can get up to speed on the changes coming in 4.0, from a back-end perspective?
Average of ratings: -
In reply to Thomas Stanley-Jones

Re: Upgrade of Moodle docs and Ad-hoc reports page

by Randy Thornton -
Picture of Documentation writers
Thomas,

First of course, thanks for wanting to contribute.

Second, I don't think the old pages are worth fixing. All the stuff I removed from the 3.11 page was really, really old. Unless a particular plugin or code has made substantial changes to the database - and if it has it is almost always noted in the release notes for that version - then it will usually work reliably in the versions of the last couple years and often older. So, it depends really on which tool the query is drawing data from.

Third, I think in general it is okay to put these from 3.10 on the 3.11 page, provided that you know it is not using any new feature from 3.11, but using a feature common to both versions. When a page rolls over to a new version twice a year, there will always be some queries that may need tweaking. That's up to the author to do, but of course, we all have lives ;) So, usually this comes up when someone tries to use them and they break. Then that should show up here in this forum.

If you are in doubt, I would always be happy to test them out on 3.11 on my own test servers. Post them and let me know and I can take a look.

About the 4.0 backend, the only reliable way to get that is really to set up a server with the beta code and look at it (code freeze was last week). Sometimes the various Tracker items will talk about changes, but often the discussions are using the api calls and there's not much in the way of discussing database changes. I don't expect a lot of changes to most parts of the database since the foucs is on UI changes and that's mostly in the theme code.
Average of ratings: -