Posted on November 9, 2009 · Posted in FHSST

We need much better management of the feedback we receive for the Free High School Science Texts project. It needs to be simple and fast and allow us to manage it easily. To help with this we’re looking to have a small feedback module written for the site. We’ll use it once we’ve upgraded the site to Drupal 6.x.

I’m looking for some development quotes and thought I might get some additional exposure if I post the draft specification on my blog. If you’re a Drupal person and would like to have a crack at this feel free to contact me with any clarifying questions or a quote for the work. I intend to make a decision by the middle of next week (18th November) so you’ve got a week to get the information to me.

FHSST Feedback Module

The FHSST site allows authors to build books in LaTeX. The original goal was to have many LaTeX-competent authors working on many sections. We have learnt that very few people are comfortable with LaTeX and PSTricks. To better accommodate people who still want to make contributions but not get their hands dirty we must provide a simple way to give the necessary input.

We would like a feedback module to be written for Drupal to help with this. This module should allow three types of feedback:

  1. errata

  2. suggested contributions

  3. testimonials

Errata

Each erratum needs to contain:

  • erratum title (mandatory)

  • detailed erratum information (mandatory)

  • book for which it is submitted (mandatory)

  • book version for which erratum is applicable (mandatory)

  • book section in which error occurs (mandatory)

  • book page number (optional)

  • submitter’s:

    • name and surname (mandatory)

    • email address (mandatory)

    • role, one of:

      • learner

      • educator

      • parent

      • other

  • timestamp of submission (recorded automatically)

  • status (only changeable by coordinator – starts in pending):

    • pending

    • corrected

    • disputed

  • timestamp of resolution (i.e. corrected or disputed state change – recorded automatically)

  • person changing state (recorded automatically)

When submitted, an erratum must go into a queue and the coordinators of the relevant book should receive an email notification that it has been submitted. They can then login and review the erratum. Once they have processed it they must be able to set it to either corrected or disputed in the case where the erratum is actually incorrect.

A page should be provided where users can see all errata submitted, the submitters’ name, the relevant book and version, and the status of the errata. The title should link to the full erratum view.

A block should be provided where users can see the 5 most recent errata submitted (title, book and status).

Suggested Contributions

This is to allow general users to submit a contribution to be included in the book by a LaTeX-enabled author. Each contribution should have:

  • contribution title (mandatory)

  • detailed contribution (mandatory)

  • attached files (optional)

  • book for which it is submitted (mandatory)

  • book section (optional)

  • submitter’s:

    • name and surname (mandatory)

    • email address (mandatory)

    • role, one of:

      • learner

      • educator

      • parent

      • other

  • timestamp of submission (recorded automatically)

  • status (only changeable by coordinator – starts in pending):

    • pending

    • incorporated

    • discarded

  • timestamp of resolution (i.e. incorporated or discarded state change to be recorded automatically)

  • person changing state (recorded automatically)

When submitted a contribution must go into a queue and the coordinators of the relevant book should receive an email notification that it has been submitted. They can then login and review the contribution. Once they have processed it they set it to either incorporated or discarded state in the case where the contribution cannot be used.

A page should be provided where users can see all contributions submitted, the submitters’ name, the relevant book and version, and the status of the contribution. The title should link to the full contribution view.

A block should be provided where users can see the 5 most recent contributions submitted (title, book and status).

Testimonials

This is simply to collect information about how the content has been used.

  • testimonial title (mandatory)

  • detailed testimonial (mandatory)

  • book for which it is submitted (optional)

  • book section (optional)

  • submitter’s:

    • name and surname (mandatory)

    • email address (mandatory)

    • role, one of: (mandatory)

      • learner

      • educator

      • parent

      • other

  • timestamp of submission (recorded automatically)

Administration

For the feedback module the books for which feedback is being received need to be configured. This should happen from the module administration page and not depend on the book module of Drupal. The administrator will add the books for the module and then add, on a book-by-book basis:

  • versions

  • chapters and sections

  • coordinators

When a book is added at least one version number is required. For each version number provided, a list of chapters and sections is required. A book will have multiple versions, each with their own unique chapter and section listing. This listing can be a simple textarea where each line is a chapter or section heading.

Each book must also have a list of coordinators who are users on the system. Coordinators should be able to access a list of all errata and contributions for their books. They should be able to view them and change the status if necessary. The time when the status is changed should be recorded.

Special Remarks

All the feedback types should be node types and should integrate into the Drupal CMS properly so that they can be integrated with other modules designed to manipulate nodes. The theming information should also be separated so that they can be re-themed.

A special page should be provided that can be used as the homepage. This page should have a customisable body of full html and then have forms for all three feedback types. This will be presented to non-authenticated users as the homepage allowing them to provide the feedback directly from the front page. We would like jQuery/jQuery UI integration in this page so that a button can be shown for each type of feedback and if clicked the form must render as a modal window. Submission using these forms should be via AJAX and should trigger an update on the blocks for the content types if they are shown.

To simplify the forms when a user selects a book the relevant versions should be loaded. Once the version is selected only the relevant sections should be loaded. Validation for all form fields should be implemented.

The module should be written in such a way to conform to the Drupal 6.X API and should only have dependencies on well established modules (modules that are actively maintained and have demonstrable support and traction within the Drupal community).

We would release all the code under the Gnu General Public Licence.

About the Author

Mark Horner is the CEO of Siyavula Education, a social enterprise working in the school sector in South Africa. While working as the Shuttleworth Foundation Fellow for Open and Collaborative Resources, Mark was able to transform the Free High School Science Texts (FHSST) project, which he co-founded, into Siyavula Education. In this process, openly-licensed, collaboratively authored textbooks have been printed and distributed nationally in South Africa. Working at the intersection of community, openness and technology; Mark intends to leverage this success to make Siyavula an innovative, technology provider in education that works effectively as part of the education community to ensure better learning opportunities for all. A recent notable event being the delivery of Siyavula's textbooks over Mxit, the most popular mobile chat solution in South Africa. Mark has a PhD in physics from the University of Cape Town and conducted his research at Lawrence Berkeley National Laboratory in California on the results from the STAR experiment at Brookhaven National Laboratory in New York. His work is carried out in the belief that the liberation of information and support of education in South Africa will lead to a peaceful and prosperous future for all South Africans.