Revision as of 07:55, 11 May 2012

This page lists the proposed specifications for the development of the OPOSSEM wiki.

Wiki Objectives

OPOSSEM, the Online Portal of Social Science Education in Methodology, is an online portal to facilitate sharing of various resources for teaching social science research methods (particularly statistical methods) among educators in secondary, undergraduate, and postgraduate settings. Little educational material is freely available to serve the needs of basic research methods courses in the social sciences, particularly political science. The creation of problem sets and lecture notes is time-intensive, and methods courses requiring such preparation are becoming more widespread across all types of institutions. This project seeks to reduce these start-up costs and enhance methods instruction by providing an online space in which instructors can share materials and information. Community members are able to post to the discussion forum, share teaching materials (syllabi, lecture notes, assignments, or working papers on teaching research methods), suggest external resources (online data source, resources for students or instructors, or published research on teaching research methods), or rate community content.

The proposed wiki-based, online textbook project responds to two needs. First, as suggested above, the range of textbook options for instructors of undergraduate research methods is quite limited. Instructors must take most textbooks as all or nothing propositions, without having flexibility to adjust content to their particular course’s learning objectives. The poor fit between the available texts and the learning objectives creates situations where students struggle not only to learn new quantitative methods that are unfamiliar and intimidating to them but must do so with examples that are not clearly related to their own political science or backgrounds. Student learning would be enhanced were they to have access to content that more clearly linked the research methods to the theories and approaches they learn in other political science class and to their own experiences.

Second, research methods textbooks are quite expensive for students, even though the core content (i.e., the equations, methods) in the text changes little from edition to edition. Compared to other textbooks in political science, research methods texts, with the costs of typesetting equations and the sometimes extensive use of figures, are often at least 50% more expensive for students. This creates a burden for students with limited resources, who cannot easily afford such texts.

The wiki-based textbook project will address both of these needs by enabling instructors to design a custom textbook option from the wiki-based content that will suit their particular course and to provide that textbook to their students in either Adobe Acrobat (.pdf) format or as a hardcopy distributed through their university bookstore at significantly reduced cost. However, before this is possible, the MediaWiki site hosting the textbook content must be developed and customized.

Wiki Content

Wiki content will include textbook topics related to social science research methods. The content will be written only by members of the OPOSSEM community, which includes both faculty and graduate students. This means editing access must be restricted to registered users.

The content will include a number of topics, ideally organized in the smallest possible units, so that instructors can combine the topics they want to have included or covered in their version of a methods textbook.

Custom OPOSSEM namespaces

In addition to the standard namespaces, OPOSSEM will have several custom namespaces:

• Introductory: Folder in which secondary or basic undergraduate versions of textbook content should be stored. Introductory content should avoid the use of equations whenever possible.<ref>So what will be left in the "main" namespace? Or, should that be the default for the introductory level materials?</ref>
• Intermediate: Folder in which undergraduate versions of textbook content should be stored. Intermediate content may include equations when needed, but should not go beyond linear algebra (no calculus, no matrix algebra).
• Advanced: Folder in which postgraduate versions of textbook content should be stored. Advanced content is likely to include many equations, including those using calculus and/or maxtrix algebra.
• Equation: This namespace holds snippets of code that format and display equations on pages. By adding equations here, it ensures that consistent equations and notation are used throughout the text. A custom extension [similar in function to the reference systems] will be developed so that on each page where an equation is displayed it adds a section at the bottom of the page labeled "Notation" or "Equation" [how to label this?] that would list in one place all the equations as a reference.
• Def: This namespace holds glossary terms and definitions. A custom extension would enable authors to 'tag' or mark any word in the text with a special link that would not only link to the definition hosted by OPOSSEM, but it would also automatically reproduce at the end of the page a list of the links to all the definitions tagged on that page (similar to the Cite extension functions).<ref>Note: One way to populate these pages would be to import the corresponding page from Wikipedia in a static version, which would provide a starting point for the OPOSSEM community to edit/refine the definition for our purposes. So during the initial drafting of the textbook, it would be good to add tags around particular words in the text that will become glossary terms (e.g., Def:Variance). Then, an admin could look at all the needed definitions and export/import the corresponding Wikipedia page, which our users could then modify/update as appropriate for our community.</ref>

Pages in the namespaces Introductory, Intermediate, and Advanced

Each page in one of these namespaces will be the core of the textbook. The pages should contain the smallest unit possible that might need to be combined to form a custom textbook chapter.<ref>OPOSSEM editors will need to write up Manual of Style and related instructions about how these namespaces/pages differ, including guidelines about their organization.</ref> Pages will have the following content or design features:

• Subpages:

1. Examples
2. Questions

• Additional content based on a custom extension like the Cite extenstion, which allows a user to tag certain text in the main part of an article but have formatted content appear after a subheading at the end of the article:

1. List of equations that appear in the topic
2. List of keywords or glossary terms used in the topic (with linked to glossary entries)
3. References

Illustration of how page content should be stored or available for editing

• Blue = main page
• Red = subpages of main page
• Green = display of any Equation namespace pages transcluded anywhere in the main page, in order of transclusion on the page
• Teal = list of words in page with an internal link to a page in the Def namespace
• Orange = Standardized references using the Cite.php extension

Example of how a registered user should be able to organize content into a new page, or chapter

Users should be able to combine pages using a custom extension (similar in function to Extension:Collection), but with hierarchy that will allow groups of pages to be combined into a "chapter" (really a page with the other pages transcluded in it) where the new page or chapter has the following format:

The key difference here is that the equations, glossary, and references would all be combined and grouped at the end of a collection of pages.

It seems there is already an effort underway to support the revision of the Collection Extension, and many of the proposed features would be things we would like our custom extension to do.

Wiki Functional Requirements and Features

Hosting configuration

Currently, the site is hosted/configured at wiki.opossem.org. However, to conform with current recommended practice, the site should be hosted at opossem.org/wiki.

The project already has hosting provided on a virtual server through McMaster University Library, and developers will be provided with the required shell and FTP access to develop and deploy the site. Upon completion of development, University staff will become responsible for updates and maintenance.

Updates

Mediawiki should be updated to the most stable recent release that will sustain the required extensions. Whenever possible, customization of standard extensions should be minimized so that the site is easily maintained. Any customization or modification to existing extensions must be documented.

Optimization and security

The site must be optimized to minimize server calls and facilitate fast page loading. The site must be secure.

Single-sign-on (SSO)

The site must implement single-sign-on using cookies (not LDAP, not OpenID, not Shibboleth, etc.) with our existing Drupal site (opossem.org), using Bakery or another similar tool. Users will sign-on only through the Drupal site (opossem.org, master) and be redirected to the Wiki (wiki.opossem.org, slave). Users will not be allowed to modify their user name or password from within the wiki, and this function should be disabled in the wiki. Any changes must be made on the Drupal site and then propagated to the Wiki site in a true "sync." That is, changes to the user name, email, or password on the Drupal site must be updated to the Wiki automatically without admin intervention nor the creation of duplicate accounts. Clicking "login" on the wiki site should redirect to the Drupal login page, and likewise, clicking logout on either site should logout the user.

User page and talk

The user talk page will keep its default features. Users should be able to customize the notification settings for their talk pages, but they should not be able to change the email address to which notifications are sent. These should always go to registered email address in the Drupal database, which is kept in sync with the user tables in the Wiki.

User roles & permissions

User roles will be defined in the Drupal site and should be synced to the user table of the Wiki site, where they will inherit Wiki permissions defined below (or in the sections on the different features).

admin

editor

member

Download/Output options

Users should be able to download any page, or collection of pages (see books below), in each of the following formats:

1. LaTeX
2. Acrobat .pdf
3. epub (cf: http://www.mediawiki.org/wiki/Extension:EPubExport)
4. Open document format (.odt)
5. HTML5<ref>[PAS: So, here's my read on this situation, but I'm not an expert on it and would be happy to hear other opinions.

It seems as though epub is clearly emerging as the dominant non-proprietary standard (and seems stable), and then there are converters which can go from epub to Kindle and mobi -- in particular, calibre, which is open source. The only major platform that currently doesn't support epub is, of course, the Kindle, but it is possible Amazon will stop being jackasses and do so, particularly since Apple and Android do support it. So seems to me we assume that epub is our "core" e-book format, and then just use converters, even though the results might not be quite a slick (though .mobi seems mostly to support a bunch of things we wouldn't use anyway). My sense -- and I say this as someone who uses Kindle software on my phone and laptop almost daily -- is that for the student audience, making sure it works on the iPad and on small laptops (MacAir and the various Windows equivalents) is more important than working on the Kindle or phones -- in particular, graphics and anything except simple equations will be really hard on a phone. And Kindles seem more common for leisure reading, and of course the older Kindles don't support color. The new "Fire" does, but seems to have disabled epub support despite running on the Android system. Though they are getting a lot of flak for this from users. But they are Amazon.

By "XML", do you mean the raw Wiki text? The other format that might be useful would be HTML5, though that might be subsumed under the XML format, and there are also LaTeX to HTML programs. MD here: Ok, so after consulting with my in-house Information Professional it seems that most people wouldn't have a need for the XML, and anyone geeky enough to need it would be able to figure out that you can already export any mediawiki page as XML using Special:Export. HTML5 would be good, however, because I might imaging someone wanting to export the textbook (or parts) as HTML5, which they then upload as a page to the proprietary Desire2Learn, Blackboard, etc. system. Again, happy to hear other opinions.] (SN: As long as people have the option to convert easily (i.e. not having to download a random converter they are unlikely to use for much else), I would support the less is more approach. As an instructor, I would be more likely to use my kindle, but I agree that my students likely wouldn't.)</ref>

Most of these output types are included in the updated version of http://www.mediawiki.org/wiki/Extension:Collection%7C.

User created books and User bookshelf

Users must be able to select a list of pages (including pages they have created in their user area, such as User:Michelle_Dion/POLS784courseoutline#Course_Policies) and easily (re)organize these pages in a customized order to form a book, which can then: be saved to the User's "bookshelf," a separate area to house their personalized collections of pages. All books on the bookshelf will be public, and any visitor can browse the books on user bookshelves.<ref>QUESTION for TEAM: Should users be able to make their own books "private"? And, how to handle hosting books for students, but also potentially giving the option of restricting access on our site to registered users? Thoughts? [PAS: If it isn't much trouble, seems fairly harmless to me. Doubt that many people will use it but I could imagine someone might -- e.g. sort of as an internal library and avoiding cluttering things for others. But not a priority]

(SN, personally, I wouldn't see myself using it. If I'm going to use a saved version of the text for class, I'm likely going to download it as a pdf or other file type and then post it in D2L/blackboard/etc. I see it as a place for me to get the version of the book I want and then give it to my students rather than sending them straight to the site. But I don't see a downside to allowing others to do it if it is relatively easy to do so. I think we should encourage people to share their version as good citizens of an open source community.) MD: OK. I'm going to leave it all public.</ref>

Registered users should be able to "save" (by copying) someone else's book to their own bookshelf. It should be a copy so that if the first user deletes the book, the copy remains.

These books should also be available to be downloaded as:

1. LaTeX
2. Acrobat .pdf
3. epub (cf: http://www.mediawiki.org/wiki/Extension:EPubExport)
4. Open document format (.odt)
5. HTML5<ref>[By registered users only? Or anyone? Or user has option to choose?] [PAS: See comments above: if we've got LaTeX, pdf and epub, there are converters into any other other format that is reasonably widespread, and otherwise we are opening a can of worms.]

(SN: I think you should have to be a registered user to download the text but obviously the whole site is available for viewing to non-registered users. I don't know why this is my preference as I can't think of any specific downside to everyone being able to download, but it would be my first instinct.) MD: Ok, I think I'll leave it "open" for now, in case instructors want to refer their students directly to their bookshelf.</ref>

These features should be like those available in the Create Book tool, but with the added provision that books are automatically be saved as associated with a particular user, and then are stored in a standardized location, named the User's bookshelf. Users should also be able to easily save someone else's book to their own bookshelf, and then have the option to edit their own version of it.

There must also be the capacity to run a query (perhaps using http://www.mediawiki.org/wiki/Extension:Validator) that audits the created textbook to ensure all internal references work (e.g. that all pages or subpages referenced in included material are included), so people don't end up with incomplete books. The query would return a list of missing pages and provide the user with the option of adding those pages.

OPOSSEM library

Visitors must be able to browse the books that have been saved by users and the saved books should be listed (or sortable) by the following characteristics:

• User name (the person on whose bookshelf the book resides)
• Most viewed (or downloaded)
• Most recently updated
• Book Title

Functions that allow contributors to easily add and organize new content

Equations

Equations must have a separate namespace and must be protected so that only editors can change equations. All textbook pages must a hidden banner (that is, that can be viewed only when editing) that advises those that edit pages on how to use existing equations in their page and where to look up the list of existing equations.

Glossary

A separate namespace will be needed for keyword definitions or glossary terms. In the text, these keywords will be marked, and should automatically be transcluded to the bottom of any page on which the section of text appears (like the reference system).

We will provide an extensive list of keywords, and the most recent Wikipedia definition for these keywords should be imported to the OPOSSEM glossary to provide a starting point for our community to edit the definitions. [PAS Query: Is the updating from Wikipedia automatic or something that we trigger manually? We would also want the option of not updating from Wikipedia to deal with situations where the Wikipedia definitions diverge (probably by getting too complex) from what we find useful, though in that instance we would probably still want to include a Wikipedia link](SN: I think the idea was just to grab some content for the definitions initially that could be edited with no further linkage or regular updating of wikipedia content intended. I could be wrong though)

Problems/Questions

Problems and/or questions should also be associated with each section of text, and these, too, should automatically 'follow' the text and be transcluded (wc?) to the bottom of whatever new page they appear upon. Again, this would be similar to the reference system.

Examples

Examples should also be associated with each section of text, and these, too, should automatically 'follow' the text and be transcluded (wc?) [PAS: 'transduction' is a word according to Wikipedia, and therefore is a word. I rather like it.] to the bottom of whatever new page they appear upon. Again, this would be similar to the reference system.

Need to be able to tag examples by field and subfield (e.g. sociology, Canadian politics, etc.) and allow selection of examples to include by these criteria (e.g. to exclude US politics examples for a Canadian textbook).

Forking/Branching Pages

Need to have option for building a "forked" page that incorporates content from an existing page but changes/adapts it to a particular approach.

Need to preserve edit history for forked pages (e.g. if someone produces "my version of regression" based on "regression", the "regression" history should be carried forward to retain attribution etc.).

Banners

• See list of Cleanup Banners to be imported (some with modifications) from Wikipedia.
• All pages in Namespaces:Introductory,Intermediate, and Advanced should have a banner (that can be dismissed) that appears only on the edit page above the edit box that says:

1. Before editing, please consult the OPOSSEM Manual of Style.
2. Use of inline equations should be limited. Instead, equations should be added to Namespace:Equation and transcluded here with tags.

• All pages in Namespace:Equations should have a banner that displays on the Namespace page but that is not transcluded with the text that says: "Warning: You are about to edit an equation that may appear on multiple pages throughout the site. Please make sure any edits conform with OPOSSEM's Manual of Style."

• Banner to warn that there are inline equations on a page.

Specific pages that should be created

Main Page

What should this have on it?

(SN: I think it would be useful to have a brief history of the what and why. At the CanCon conference there was a lot of discussion the first day on what added value this project had to what was already available and how it fit into other markets. I assumed that a lot of the value added was relatively obvious, but it wasn't so we should take time to explain that somewhere.

Once someone is logged in, this page should have a direct link to their bookshelf, and, if possible, it would be nice to have a memory built in so that you could see your most recent activity on the book (last page edited, etc.)

How to get involved

This page will have text that invites OPOSSEM community members to get involved, with a number of suggestions.

This page must also include lists of the following pages:

All the pages in the OPOSSEM namespace

All the pages listed in the Maintenance reports section of Special:SpecialPages

All the pages listed in the List of pages section of Special:SpecialPages

Tools for Editors

This page should include the relevant links for editors to use. This includes all the links in the Quality Assurance section of Special:SpecialPages.

Anything an editor can do but that no other users can do should appear on this page to make it easier for editors to see what tools they have.

Official page versions

Each July 1 (or thereabouts), editors will review changes to the pages since the last official version of the page and "approve" changes to create the official/protected version of the page.

Visitors and members can view either the current version of the "official/protected" or 'flagged' version of pages.

There must be a page that lists all "flagged" or reviewed pages, with the date of their most recent review.

See Special:ReviewedPages. Question for Team: Need to figure out how to explain this because we'll want annual editions of the textbook to stay static. [PAS: Correct, and version control is really important, but I'm guessing that in the early stages, annual will be too infrequent -- what about starting at least with the assumption of two updates a year, 1 Jan and 1 July, or maybe 1 Dec and 1 June so people have some time to get changes in place before the start of the winter semester/quarter]

• Need a query for pages that are in the system but have never been reviewed (ReviewedPages only includes pages that have been reviewed at least once).

(SN: Query: What happens if I have my saved version of the book, which only includes the sections I find relevant, and then the static version of the text changes to include the new revisions? Will my book now have all of the sections I chose but with the most current revisions, or will it have the revisions as of the time I created my book? If I plan to use the same version year to year, I can see the advantages of both. It would be nice if when I created my book I had the option of whether or not I wanted revisions to automatically be updated or not or perhaps just an email or a message the next time I logged in that asks if I want to incorporate the revisions into my version.)

User contributions

User contributions must be displayed in a way that is easy for external reviewers/department chairs to "see" and evaluate. The default page view for User contributions (e.g., Special:Contributions/Michelle Dion) does not meet this requirement. [PAS: Have we had any further feedback on what reviewers/chairs would like to see in this regard? I could drop a line to the PolMeth fellows list --- which has a lot of former administrators, but mostly research universities --- and see if I get any ideas; is there something comparable we could get on the liberal arts college side? Also if we need some customized code for this part, I'm willing to put some work in on this piece (all the more so if that code could be perl or Python...)]

In addition to the default contributions view, a custom view should be created for each user that will each page the user has edited. When the link to that page is clicked from this list, it will return a copy of the current page with the following characteristics:

Display current version of page with content contributed by user (black) and others (grey) plus:

• Any text added by user that has been subsequently deleted by any other user (Black text with strikeout)
• Any text that was added by another user that was deleted by user (Grey text with strikeout)
• Any deleted text from other users should not be displayed.

Sample Color Key:

• Black text = Contributed by user
• Grey text = Contributed by another user
• Black text with strikeout = Text contributed by user and deleted by another user
• Grey text with strikeout = Text contributed by another user and deleted by user

Example

Question for team: Should dates be included?? How/where?

(SN: I think dates are a good idea, and the field will already be collected. Could we have the date show up when you scroll over the edit with your mouse? That seems like the most convenient place, but it wouldn't be printable.)

Others?

PAS:

1. We need a facility for sending alerts to the editors in case of incorrect/inappropriate content

Wiki visual design

The MediaWiki skin or website design must incorporate design elements from the existing OPOSSEM Drupal site. In particular, the Wiki site must:

1. Use visual elements, the logo, and colors already in use on the Drupal site
2. Not use a theme that looks in any way like the default Wikipedia theme

The wiki need not look exactly like the Drupal site and indeed should look more like a book or wiki site than the main Drupal site. That is, the Wiki theme need not be fully integrated into the main Drupal site, but the two sites should share common design elements and a similar 'look'.

Skins

Free Wiki Skin seems fairly similar already to the main site, and perhaps could be easily adapted for OPOSSEM. Another skin that has a very different feel from Wikipedia and would perhaps be easy to adapt to look like OPOSSEM is Erudite.

Wiki extensions

All active extensions are listed on the Special:Version page.

List of special extensions for reference:

• Semantic MediaWiki
• Collection - create books
• Delete Batch - deletes a batch of pages
• Flagged Revisions - Gives Editors and Reviewers the ability to review revisions and stabilize pages
• Nuke - Gives administrators the ability to mass delete pages
• SpecialInterwiki - Adds a special page to view and edit the interwiki table
• User Merge and Delete - Merges references from one user to another user in the wiki database - will also delete old users following merge. Requires usermerge privileges
• AuthDrupal - Signin integration for MediaWiki as slave of Drupal.
• Category Tree - The CategoryTree extension provides a dynamic view of the wiki's category structure as a tree
• Cite - Adds <ref[ name=id]> and references /> tags, for citations
• InputBox - Allow inclusion of predefined HTML forms
• ParserFunctions - Enhance parser with logical functions
• SyntaxHighlight - Provides syntax highlighting using GeSHi Highlighter
• FCKeditor - FCKeditor extension for editing wiki pages (WYSIWYG editor)
• Preloader - Provides customisable per-namespace boilerplate text for new pages

Wiki Template Messages

For reference: wikipedia:Wikipedia:Template_messages/Cleanup

Notes