Docs:Rationale

For several years, APEcs' (formerly PEVE's) course development activities conformed to fairly standard distributed development models found in many complex multi-contributor systems. While there are established practices and patterns aimed at dealing with the concurrency problems such situations introduce, these have proven only marginally effective in practice for various reasons, including

• The large amount of binary data (especially image and animation files) involved in courses and course development. Conventional client-server concurrent versioning systems generally do not handle binary data easily or effectively.
• The software required to effectively utilise and interact with concurrent versioning systems vastly over-complicates what should be a fairly simple process. This is a barrier to uptake and ease of use.
• People working on local versions of material may not push their changed back into the central system as regularly as needed.
• CVS, SVN, and almost every other concurrent versioning system out there, are frankly utterly hideous to use in practice.
• Previous practices have lead to ambiguities between multiple versions of course material spread over various systems (the whole CVS + SVN + copies on shared filestores + local copies nightmare)

The latter point is the most dramatic and serious visible problem with the application of conventional multi-contributor distributed development tools to course development, and the effects go far beyond simple ambiguities about which version of a given document contains the most recent and correct information: there are serious problems of data loss potential, inherent difficulties in properly backing up material, and complicated conflict resolution overheads.

An Alternative Approach

While considering the conversion of the C course material, and the overall architecture of APEcs' course development resources, it became obvious that established methods for managing development of course material had introduced complexities, barriers, and outright nightmarish problems that could not be easily solved without a major shift in development practice.

Chris has a number of personal projects whose development is documented and supported via a MediaWiki installation running on his personal server. His experience with that system of development suggested an alternative direction for APEcs course development that could mitigate or entirely avoid many of the significant problems encountered with development thus far: develop courses directly in MediaWiki, and then extract the content from the wiki to process through the course processor. This has a number of significant advantages:

• There would be an absolutely definitive, always current version of each course in the wiki. There would be no need to have local copies of the content, as all editing could be done in-place in the wiki. Nothing can prevent authors from creating material locally, and then adding it to the wiki, but this does not introduce ambiguities about versioning in the same way as the old system: if it isn't in the wiki, it isn't considered part of the material.
• MediaWiki keeps full histories of all edits, and retains histories for binary files too, with no need for a separate, cumbersome versioning system like cvs, svn, git, and so on. MediaWiki's history handling is also vastly more user-friendly and intuitive.
• Multiple editors could operate on the same course at the same time, and MediaWiki's change conflict resolution system would handle any potential merge problems.
• The vast majority of the course material developed to date uses HTML that is directly supported in MediaWiki, and special tags understood by the processor are passed through untouched.
• Editing content becomes much easier, with all the advantages of authoring in html without the overheads of needing a special editor, or managing large numbers of step files by hand.
• Exporting content from MediaWiki is simple, and the XML format it produces can be processed as needed without significant effort.
• Importing content is similarly simple, once material has been processed into the required XML schema.

The conversion of the C course has been used to test this development process, and it appears to be a success. While additional testing and investigation is needed, it certainly seems like the use of MediaWiki to support development will help avoid or mitigate all the major problems with course development organisation.

Future Possibilities

Please see Docs:Course_design_issues