Actions

OPOSSEM

Difference between revisions of "Specifications"

From OPOSSEM

(Official page versions)
Line 172: Line 172:
 
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.
 
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.
  
==Official page versions==
+
== Official page versions ==
The [http://www.mediawiki.org/wiki/Extension:FlaggedRevs Flagged Revisions Extension] (or a comparable alternative) should be used so that Editors can approve changes to particular pages.
 
  
Each summer (and perhaps winter, too), editors will review changes to pages since the last official version of the page and "approve" changes to create the official/protected version of the page.  
+
The [http://www.mediawiki.org/wiki/Extension:FlaggedRevs Flagged Revisions Extension] (or a comparable alternative) should be used so that Editors can approve changes to particular pages in the Main, Introductory, Intermediate, and Advanced namespaces. The default view of any page should be the "live" wiki version of the page (including any changes that have yet to be approved).  
  
Visitors and members can view either the current version of the "official/protected" or 'flagged' version of pages.  
+
Each summer (and perhaps winter, too), editors will review changes to pages since the last official version of the page and "approve" changes to create the official/protected version of the page.
  
There must be a page that lists all "flagged" or reviewed pages, with the date of their most recent review.  
+
The [http://www.mediawiki.org/wiki/Extension:FlaggedRevs Flagged Revisions Extension] may need to be customized or modified to archive each of these "approved" versions, which should be stamped with the year/issue of the revision. For instance, the "official" versions will numbered:
 +
* 2012.1
 +
* 2012.2
 +
* 2012.3
 +
* 2013.1
  
See [[Special:ReviewedPages]].<ref> '''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]. MD: You're right, Phil. And we can decide how frequently the review/approved versions get updated later. Right now, we need to provide feedback about how we would like these archived versions to be organized/stored.</ref>
+
This will allow users to find the most recent "stable" version, but also have a numbering system that is flexible enough for editors to adjust the "issue" or version timing.<ref> '''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]. MD: You're right, Phil. And we can decide how frequently the review/approved versions get updated later. Right now, we need to provide feedback about how we would like these archived versions to be organized/stored. '''In particular,''' we need to decide if we want to request custom categories of review status (see http://www.mediawiki.org/wiki/Help:Extension:FlaggedRevs#Terminology, for the defaults), or if we just want to tell the wiki developers that we want the 'stable' version to be based on the most recent version of a page that meets some certain threshold across the 3 categories, for example: Accurate, Moderate, Good.</ref>
  
(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.)
+
There will need to be the possibility for a registered user to view/download/save to their book collection any of the prior "stable" versions of their choosing.
  
 
== Download/Output options  ==
 
== Download/Output options  ==

Revision as of 15:29, 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


Error creating thumbnail: Unable to save thumbnail to destination

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:

Error creating thumbnail: Unable to save thumbnail to destination

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.

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. Again, it looks like a proposed revision of Collection would have many of these features included.

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.

The default output for the Create Book tool includes a list of contributors to the individual pages. For example:
Error creating thumbnail: Unable to save thumbnail to destination

This must be modified to include after each contributor's name in parentheses the percentage of the character count contributed by that user. The contributors should be listed in descending order of percentage contribution (i.e., with the person with the greatest percentage contribution listed first). In particular, the percentage should be calculated as = # of characters contributed by user/the total number of characters on the page.

In addition, as explain above, the Notes and References for each page should appear at the end of the chapter, rather than after the page. In addition, all equations that appear in the chapter should also appear again after a Subheading "Equations"<ref>Or, should this be "Notation"?</ref>.

All words tagged as definitions should also appear at the end of the chapter after a subheading "Definitions."<ref>Should this be "Glossary Terms" or some other name?</ref> This should just be a display list at the end of the Chapter. At the end of the Book, all the words that appear on any page should be listed under a Heading as Definitions, and the full text of the Definition entry should be printed there.

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

Ideally, next to each title/book, there would be a "downloads" count displayed.

Creating and organizing new content

Preloaded content for pages in particular namespaces

  1. New pages in the main content namespaces (Main, Introductory, Intermediate, and Advanced) should be preloaded with the content necessary to execute all the features needed. For now, an example, using the Preloader Extension, can be found at here.
  2. New pages in the Def namespace should be preloaded with the contents of Template:Definition.
  3. New pages in the Equation namesapace should be preloaded with the contents of Template:Equation.

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.<ref>[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) MD here: Yes, the idea is to import some initial content from wikipedia, which our community would then prune/edit for our purposes.</ref>

Examples, Problems and Questions

Examples, problems and/or questions should also be associated with each section of text, and be included as subpages of the main page/section of text. The main page should display at the bottom of the electronic version a list of the subpages below that page. This can be accomplished with the Extension:SubPageList and code like

= Examples, Problems and Questions = <subpages format="ol" pathstyle="no" showpage="no" kidsonly="no" />

This list should appear in the online version, but should be excluded from the print or book version (see [http://en.wikipedia.org/wiki/Category:Exclude_in_print Category:Exclude_in_print). Users will still have the option of manually choosing or adding the questions, examples, etc. included as subpages to their books for printing/downloading.

Example subpages should be tagged by field and subfield (e.g. sociology, Canadian politics, etc.) using categories.<ref>NOTE: This is another custom/manual item that will need to be explained in the OPOSSEM documentation by someone.</ref>

Forking/Branching Pages<ref>Please see if my edits below capture the intent.</ref>

A custom extension (perhaps based on Extension:Duplicator) should be developed to have the following features/options:

  1. In the toolbox on each page in the Main, Introductory, Intermediate, and Advanced namespaces, a link should appear that says "Copy page." When clicked, this should take the user to the Special:Duplicator page, and prepopulate the page to be copied in the appropriate field.
  2. The Special:Duplicator page should give the user two options (as toggle buttons) for where to save the new copy of the page: as a subpage of the original page being copied OR as a subpage in the user's storage area. Above or below these two options should appear the following text: "You are about to create a new copy of this page. Before you do so, please review the related pages in the other Namespaces to see whether they might meet your needs. If you believe there is an error on this page or that it could be improved, please consider editing the page itself or start a discussion its Talk page. If you must create a new copy, please store personal versions in your user storage area. If you believe your new version is an appropriate fork or variation, please save it as a subpage of the page you are copying."
  3. The copied page should retain all the revision history and contributor information, for attribution purposes.

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.

Math

The latest versions of Mediawiki have removed the Math feature from the core. However, our users need the ability to use the <math> tags to add mathematical notation using LaTeX.

Extensions & Templates

All the templates necessary to ensure proper function of an installed Extension should be imported and revised as necessary for use in OPOSSEM.

Distribution of custom extensions or features

The developer is encouraged to contribute any custom extensions or tools developed for the OPOSSEM wiki to any and all relevant open source repositories. It is requested that the extension files acknowledge support from the OPOSSEM project (opossem.org) and the Centre for Leadership in Learning at McMaster University (cll.mcmaster.ca).

Optimization and security

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

File uploads

Image and other file uploads should be configured to allow the largest upload allowed by the McMaster virtual server configuration, and the file upload page should include this file size limit. It is currently 7MB, but ideally would be up to 15MB.<ref>Michelle needs to check with John to see what the limit is.</ref>

Currently, the permitted file types include: png, gif, jpg, jpeg, doc, xls, mpp, pdf, ppt, tiff, bmp, docx, xlsx, pptx, ps, odt, ods, odp, odg.

To this list should be added the following file extensions:<ref>Team: what other file types might we need/allow? As an aside, we had a discussion in Toronto about developing a recommended practice of uploading one-off images or files directly to the wiki, but that if a user had a custom dataset or .do file to modify a publicly available dataset for the purpose of contributing multiple examples to the textbook, they should add the files to the "intstructional materials" part of the main site, and link to those anywhere in the textbook that the files are used.</ref>

In addition, the Licensing fields of the Special:Upload page should be configured to include the following options:

  • CC BY-NC-SA (set as default)
  • CC BY-NC-ND

and

On the Special:Upload page, below the Licensing field, there should be the following text: Additional information about Creative Commons license options can be found here.

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.

Official page versions

The Flagged Revisions Extension (or a comparable alternative) should be used so that Editors can approve changes to particular pages in the Main, Introductory, Intermediate, and Advanced namespaces. The default view of any page should be the "live" wiki version of the page (including any changes that have yet to be approved).

Each summer (and perhaps winter, too), editors will review changes to pages since the last official version of the page and "approve" changes to create the official/protected version of the page.

The Flagged Revisions Extension may need to be customized or modified to archive each of these "approved" versions, which should be stamped with the year/issue of the revision. For instance, the "official" versions will numbered:

  • 2012.1
  • 2012.2
  • 2012.3
  • 2013.1

This will allow users to find the most recent "stable" version, but also have a numbering system that is flexible enough for editors to adjust the "issue" or version timing.<ref> 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]. MD: You're right, Phil. And we can decide how frequently the review/approved versions get updated later. Right now, we need to provide feedback about how we would like these archived versions to be organized/stored. In particular, we need to decide if we want to request custom categories of review status (see http://www.mediawiki.org/wiki/Help:Extension:FlaggedRevs#Terminology, for the defaults), or if we just want to tell the wiki developers that we want the 'stable' version to be based on the most recent version of a page that meets some certain threshold across the 3 categories, for example: Accurate, Moderate, Good.</ref>

There will need to be the possibility for a registered user to view/download/save to their book collection any of the prior "stable" versions of their choosing.

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.

Banners

For reference: wikipedia:Wikipedia:Template_messages/Cleanup

Additional banners that should be created for OPOSSEM use

  • 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.
  • Banner to warn that there are inline equations on a page, perhaps based on this cleanup template.
  • 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."<ref>Team: Any other banners or special headlines that we might need to appear on the site?</ref>

User roles & permissions

Visitors to the site who are not registered users (through the main Drupal site) may read pages and browse the OPOSSEM library (including downloading versions of collections/books listed there). They should also be able to "export" pages using the export function. They should not, however, be able to create collections/books or edit any pages.

Other user roles for registered users will be assigned in the Drupal site and should be synced to the user table of the Wiki site, where they will inherit Wiki permissions defined below. Additional permissions/restrictions are included in descriptions of specific extensions/functions elsewhere in this document.

Since all users will inherit their user group from the Drupal site, the Special:UserRights page should be disabled for all users except Admins.

Users should be able to belong to multiple groups, or inherit rights of the group below them where the hierarchy is:

  1. Admin,
  2. Editor, and
  3. Contributor,

unless an exception/deviation is noted below.<ref>See Special:ListGroupRights for a list of group rights.</ref>

action Admin Editor Contributor
Inherit all default Bureaucrat rights X
Inherit all default Reviewer rights X X
Inherit all default User rights X X X
Edit pages (in default & main Namespaces, including Intro, Intermediate, Advanced, etc.) X X X
Edit templates X X
Create pages (in default & main Namespaces, including Intro, Intermediate, Advanced, etc.) X X X
Create templates X X
Create equations X X X
Edit equations X X X
Create definitions X X X
Edit definitions X X X
Import pages X X
Delete pages X
Protect pages* X X

*This is a deviation from the usual group permissions.

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.<ref>[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...) MD here: No, we haven't had any feedback on this specific feature. My thinking was that we needed to have a way to show a list of pages to which a person has contributed, and then, each page should clearly show what portions of the text was contributed by the particular user (as opposed to others). So, that was the goal of the formatting below. All this content is stored in the database, it's just a matter of having the programmer put together a custom view that pulls the various pieces together as needed. I think this is something the developer(s) should be able to do.]</ref>


In addition to the default contributions view (for example, Special:Contributions/Michelle_Dion), a custom page/view should be created for each user that will list each page or subpage the user has edited. Next to the title of the page on this list, the names of all the contributors to the page in descending order of percentage contribution (like the printed book contribution section: OPOSSEM:Specifications#User_created_books_and_User_bookshelf) should be listed. After each name, it should also include the date of the most recent revision to the page by each user. For instance: Michelle Dion (55%, 2012 May 10), Phil Schrodt (28%, 2012 May 5), and Shane Nordyke (17%, 2012 May 6). Those who have contributed fewer than 3% of the characters and/or all of whom's edits were marked as "minor edits" should be excluded from the calculation and list. In addition, there should be a link to "Download .pdf version" in this list, which when clicked would produce a .pdf version like that described below.

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

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur bibendum ullamcorper viverra. Donec malesuada nulla nec augue aliquam eget mattis justo lacinia. Nunc mattis tempor lorem nec scelerisque. Donec aliquam tincidunt arcu, a egestas ante ultrices eget. Curabitur neque orci, rhoncus vitae gravida eu, blandit in nisl. Aliquam dui nisi, tincidunt sit amet lobortis gravida, rutrum eu elit. Donec lacinia, ante dignissim auctor dapibus, nulla nunc accumsan enim, eget vestibulum nibh est at mi. Ut enim eros, iaculis et fringilla sit amet, ullamcorper non urna. Nunc id semper sapien.

Cras faucibus malesuada pellentesque. Phasellus vitae magna diam, non iaculis dui. Aliquam hendrerit pellentesque ipsum, quis accumsan risus adipiscing nec.In vel tellus orci. Donec libero nunc, tristique non bibendum viverra, fermentum ut leo. Cras porta pharetra justo. Nulla aliquam placerat leo, a eleifend ligula tincidunt in. Maecenas dapibus, urna quis varius tincidunt, diam magna hendrerit massa, eget eleifend sem ante et massa. In et lacus ut quam venenatis consequat sit amet vitae eros. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin vulputate imperdiet nulla vel varius. Sed porttitor suscipit venenatis. Aenean tortor velit, sodales porttitor dapibus non, rhoncus ac lacus. Quisque aliquam adipiscing nisl at adipiscing. Pellentesque sodales sem a quam consequat tincidunt. Etiam orci eros, placerat in rhoncus a, tempor ut sapien.

Morbi tempor libero vitae neque consequat tristique. Morbi nisi dui, egestas at faucibus sed, tempor eu risus. Quisque faucibus molestie lectus, quis feugiat metus lobortis sit amet. Aenean et fringilla est. Sed turpis est, tempus ut aliquam id, consequat sed enim. Suspendisse interdum arcu sit amet tellus fermentum nec egestas purus scelerisque. Praesent at molestie quam. Proin eget augue vitae justo porttitor sodales. Nunc et lectus vitae nulla fringilla interdum non sit amet ante. Sed nec nibh ligula, non venenatis mi. Curabitur ultrices, nisl id faucibus laoreet, purus mi tempor tellus, id iaculis ipsum eros sed turpis. Curabitur luctus erat fermentum augue mattis ac dapibus mi lacinia.



At the bottom of the online page view, it should display a list all the contributors to the page in descending order of percentage contribution (like the printed book contribution section: OPOSSEM:Specifications#User_created_books_and_User_bookshelf. After each name, it should also include the date of the most recent revision to the page by each user. For instance: Michelle Dion (55%, 2012 May 10), Phil Schrodt (28%, 2012 May 5), and Shane Nordyke (17%, 2012 May 6). Those who have contributed fewer than 3% of the characters and/or all of whom's edits were marked as "minor edits" should be excluded from the calculation and list.

The page should also have a button at the top or bottom of the page that says "Download this page," and when clicked, it would produce a .pdf version of the page to be viewed in a new browser window or downloaded, and the downloaded page should also include the formatted list of contributors, including their percentages.<ref> 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.)</ref>

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 a list of links to the following custom pages:

  1. A page that lists all the pages in the OPOSSEM namespace
  2. A page that lists all the pages in the Help namespace
  3. A page that lists all the pages in the Introductory namespace
  4. A page that lists all the pages in the Intermediate namespace
  5. A page that lists all the pages in the Advanced namespace
  6. Special:FewestRevisions
  7. Special:ShortPages
  8. Special:UnwatchedPages
  9. Special:WantedPages
  10. A page that lists all the pages tagged with one of the cleanup banners
  11. A page that lists all the pages that have been marked by Editors as sighted, basic, or good (or lower) (see: http://www.mediawiki.org/wiki/Help:Extension:FlaggedRevs#Terminology Flagged Revisions Terminology]
  12. Special:UnreviewedPages


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.

There should also be a link to a list of Special pages generated by the Flagged Revisions Extension, including:

These links will enable editors to quickly find a list of pages that need review since the last set of reviews.

In addition, there should be a link to view all pages tagged with banners that warn of inappropriate content. Editors should automatically be notified by email when any page gets one of those banners added.<ref>PAS:We need a facility for sending alerts to the editors in case of incorrect/inappropriate content. MD: I think this should work. However, we need to identify a list of the banners that we think we should be notified about. Here's an annotated list of available clean up banners: [1], many of which (and some others), I've already identified to be imported and/or modified for our use (see OPOSSEM:Specifications/CleanupBanners. Once development begins, someone will need to let the developer know which of these clean up banners should trigger a notification. </ref>

Others?

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:

  • 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
  • WYSIWYG extension - Extension for editing wiki pages (WYSIWYG editor) [The newer versions of Mediawiki have a built in WYSIWYG editor.]
  • Preloader - Provides customisable per-namespace boilerplate text for new pages
  • SubPageList - Provides facility to list subpages on their parent page
  • Validator - supports SubPageList

Notes

<references group=""></references>