OER in Education:Documentation

From OER in Education
Revision as of 23:41, 2 December 2014 by Bjoern (talk | contribs)

General

Extensionsː

  • Reviewed topcontent ← needs adding to github somewhere (e.g. mine)
  • Reviewed magicnumeredheadins ← needs adding to github
  • Reconfigure the search feature ← needs documenting
  • Optimize the page delivering (more caching) ← needs documenting
  • Search engine crawling restrictions ← needs documenting
  • Setup social extentions working with togetherJS ← need to refer to some installation docs elsewhere (“We followed these instructions …”)̈
  • Setup new OCG toolchain with Collection extension (still buggy) (for pdf generation) ← need to refer to some installation docs elsewhere; Also, what’s the ETA for improvements?
  • Setup auto. ZIM generation toolchain ← need to refer to some installation docs elsewhere
  • Configure solution for article section prefixing ← needs documenting

Optimisation and upgrading

Reconfigure the mediawiki in a way it make it easy to upgrade

  • Includes re-configuring the css to be contained in “Mediawiki:Vector.css”
  • Setup the scripts to backup/upgrade easily ← need to document how we can do these updates, including OCG tool chain.

Mediawiki backup & upgrade

OER server has an all-in-one solution to backup the MW instance and replace the MW code by an other (newer one). To achieve to do this, the script only needs a master directory with the newer Mediawiki (with a configured LocalSettings.php and all necessaries extensions. The script is localised current at /home/kelson/updateMediawikiInstance.pl (call it without argument to learn how to use it). The code repository of this script is here.

To update OCG, Parsoid, mwoffliner and Semantic Mediawiki you should refer to the original documentation.

Caching

OER use a few technics to improve responsiveness of the web site:

  • Memcached to cache the rendered HTML (see /var/www/w/LocalSettings.php)
  • Nginx customized virtual host configuration (see /etc/nginx/site-availables/oer)

Robots

Have a look to the robots.txt file.

Incremental backup

The incremental backup is done every day using rsnapshot (and a cron entry).

Custom extensions

OER has a few extensions which are non-standards or/and lightly customized. They are available in /var/www/custom/extensions/


Usabilty and accessː Offline

PDF

Assessment of pdf generation. We currently generate our own multi-chapter pdf (using a set of scripts), as we have not found the pediapress pdf generation suitable for our type of content. We would like to explore what other pdf production tool are being worked on, and would like to feed Higher Education requirements into that process.

ZIM generation

One time a month a new ZIM file of OER is generated automatically using mwoffliner (and crontab, zimwriterfs, ...)

Usabilityː General

Search

We did some user testing, and the wiki search came up as something that users found confusing, and not really useful for finding the content they were looking for. We currently use a Google custom search, but the integration into the wiki is not ideal. We would like to explore options for searching that allows our audience to find relevant content more easily.

How did we do this? → See LocalSettings.custom.php and “../custom/extensions” directory.

The Mediawiki search future is customized. It display the results of the standard search engine conbined with the results of Google. This is done using the "GoogleSiteSearch" extension. See the file LocalSettings.custom.php to see how it's configured.

Social tools

We have installed TogetherJS on OER using the TogetherJS Mediawiki extension.

Visual editor

Usabilityː Navigation

Project navigation: Page banners

Project specific page banners. On our wiki, different "projects" have different “page banners”, i.e. a section at the top of the page that identifies the project. Compare e.g. http://oer.educ.cam.ac.uk/wiki/ORBIT, and http://oer.educ.cam.ac.uk/wiki/OER4Schools. In order for projects to choose to place their outputs on a departmental site (let alone a University wide, or wikibooks), they need to have their own identity within that site. Otherwise it is simply not acceptable to project stake holders. We have an existing mechanism for this, but it uses the 'site notice’, so we cannot have site notices, and it relies on an actual source code modification, which makes it difficult for us to upgrade.


Navigation page collections

Collection extension

Wiki navigation between pages. We currently have a mechanism (relying on the semantic extension) that allows several wiki pages to be grouped into a collection, displaying a navigation menu on each page, see e.g. http://oer.educ.cam.ac.uk/wiki/OER4Schools/Questioning#menuexpand. We would like to assess our implementation of this, and optimise it.

Creating Navigation

<noinclude>{{saved book |title= |subtitle= |cover-image= |cover-color=}} </noinclude> :[[Dolphin]] :[[Toothed whale]]

Section Number Prefixing

Section numbers. When creating longer documents, it is important that each section has a unique number. We would like to be able to prefix the usual page section numbers (1, 2, 3, …) with a chapter number (say “5”, to give 5.1, 5.2, 5.3, …; or say “A”, to give A.1, A.2, A.3).

  • <null>1 → Appendix A - 1
  • <null>1.1 → Appendix A - 1.1

The use of our longer documents (sometimes numbering 100s of printed pages) has been confusing during e.g. during workshops because of the lack of unique section numbers across several pages. (“Let’s look at chapter 5, section 3.” - “No, not this section 3, go to chapter 5 first, then section 3.” vs. “Let’s look at section 5.3.”).

The OER Mediawiki is configured in a way to allow to specify a prefix before section titles. This prefix can be set using the Template:SectionPrefix and use the extension:CSS.

MLEB

Future work

  • Potential hackathon
    • Investigate improvements to OER4S-ZIM
    • Investigate improvements to OCG and pdf.
    • Add documentation to wiki for various tools (such as collabJS), as well as basic wiki editing info… Where’s a course on wiki editing?
  • Explore collab editor.

Also we are running an event for Faculty, focussing on content production with these new tools (such as visual editor, navigation, etc).