Brad Miller edited this page Mar 28, 2016 · 38 revisions

High Level Goals and Current State (March 2016)

  1. For book authors: Runestone should become the LaTeX for writing interactive books.

    • A small number of authors have created books using RuneStone, either from scratch or by forking and editing existing books. The following authors have created books that they have made publicly availalble:

      • Brad Miller
      • David Ranum
      • Mark Guzdial
      • Barb Ericson
      • Paul Resnick
      • ...perhaps others that we don't know about! Please tell us.
    • Currently, authors do the following to get started

      • install RunestoneComponents, by executing pip install runestone
      • run runestone init (or git clone a github fork of one of the existing books in order to edit it)
      • run runestone build
      • run runestone serve to access the book via http://localhost from a browser
      • edit the files inside the /_sources folder to change the contents of the book
    • To make the book available through a server that the author runs, the author needs to:

      • configure a webserver and SQL DB
      • install RunestoneServer, via git clone of a github fork of the RunestoneServer repo
      • git clone their book inside the books/ directory of the RunestoneServer installation
    • To contribute a book they have authored back to the public Runestone library, authors need to communicate directly with Brad Miller, and have him make a fork of their book from the Runestone github account and make it available on the public server that he runs (

    • The system seems to be working pretty well already. In spring/summer 2016, we are planning just one improvement:

      • To aid authors in making their textbooks available via, we will develop capabilities for automatic deployment via an automation server that monitors github repositories for those textbooks.
  2. For teachers: Runestone should provide a library of free online interactive textbooks and services that make it easy to offer a course built around one of those textbooks.

    • The site provides a free hosted service, where teachers can instantiate a new "course", and then have their students sign up to be part of the course. The site is very successful.

      • This part has succeeded beyond my wildest dreams.
      • Hundreds of high schools
      • Hundreds of colleges and universtities
      • Thousands of individual learners
      • Unique daily visitors has grown to nearly ten thousand
      • However, the infrastructure is definitely showing its age, and needs an update.
    • In spring/summer 2016, we would like to do a number of things to improve the experience for teachers

      • Improve the splash page and documentation so that teachers know what they can do and how to do it
      • Improve the authoring tools for teachers to create daily/weekly activities for their students to do
      • Make more activity types gradable
      • Improve integration with LMS like Sakai, Moodle, and Canvas
      • Enhance the community of practice that is growing around the email list
  3. For students: Runestone should provide online books with interactive features that enhance learning.

    • Many features are working very well, including:

      • ActiveCode windows
      • Multiple choice questions with feedback
      • Parsons problems
      • Automated feedback via Unit Tests
      • Time quizzes
      • And several others
    • In spring/summer 2016, we would like to:

      • Add additional features to Parsons problems (Georgia Tech)
      • Make UX improvements in a few areas where there are frictions currently
  4. For Runestone developers: Runestone should be an easy community join.

    • Currently, there are a handful of developers who are making contributions to RunestoneComponents and/or RunestoneServer. They do this by forking repos on github, editing and testing on their own machines, and then making Pull Requests on github back to the original repositories.
    • Runestone incorporates terrific tools from other open source projects, including Sphinx and skulpt. Some Runestone developers have also participated in those projects.
    • In spring/summer 2016, we would like to:
      • Improve the documentation for how to get started as a Runestone developer.

Support for Teachers

Editing and Adding Student "Task Pages"

You want to think about this section in terms of an RST code generator. The result of pressing the teacher pressing the submit button for a page will be an RST file that will need to be generated.

  • Add an admin screen whereby instructors can add and reorder multiple Student Task Pages.
  • Add an admin screen where an instructor authors/edits a single Student Task Page.
    • Top section is for reading assignments. Let the instructor click on chapters or subchapters from the Table of Contents, to assign them. Let the instructor specify a deadline. Let the instructory specify whether this is a graded usage assignment, and if so, how much time or what percentage of the possible activities they need to interact with. Let the instructors specify external links to outside web pages or videos that they should look at.
    • Next section is for a problem set. Create an interface that would allow instructors to select from existing problems (and assign point values to them. Create an interface for an instructor to add their own problem (by authoring .rst formatted text using one of the runestone directives like .. actex). Let the instructor specify a deadline for the problem set.
    • Make a preview
    • Create an import/export button to get the rst or submit the rst that is generated by this admin screen
  • Add a dropdown to the general page, next to the Table of Contents button, for students to get to the instructor authored Task Pages.
  • Add an exercise directive in RunestoneComponents. It takes the contents and store them in the DB, so that they can be made available in the interface for instructors to select existing problems for a problem set.
  • Rewrite exercises at the ends of chapters in existing books to use the new exercise directive.
  • Tighten up login checking to make sure you are only allow on the courses you are registered for.
  • Assignment types need to be configurable for the course rather than for the entire site
  • Assessments (multiple choice, parsons, etc.) should be autograded when they are part of an assignment
  • Allow for additional assessment of programming problems using regex matching against the source. This can be accomplished by appending an assignment statement of the fom __source = before appending any suffix code. Then suffix code can refer to __source
  • Add a mechanism for allowing teachers to copy their Student Task Pages from a previous course

Login management

  • generalize course_instructor table to course_user table
  • add a field to course_user to say what level of privilege they have (student or instructor)
  • use the user_state table to direct a user to the last course they were logged in
  • Add a menu item for instructors and students to switch to any course they are registered for
  • Add a field to auth_user for an external identifier. This will be included as a column in the grades .cvs that can be exported, and will aid with merging the data with other sources the instructor may have (e.g., an external gradebook)
  • Add a tabular admin interface to allow an instructor to edit two fields associated with each of the people registered for their course:
    • student vs. instructor privilege level
    • The external identifier field
  • Change the profile form to allow the user to register for an additional course
  • For all reports include first, last, email address, and extenrnal id (if set) to identify the student.
  • Add a field to the course to allow/disallow registration for a course. Make this field be settable on the form for creating/editing courses.
  • Create and enforce a policy and enrolling/un-enrolling students. Currently the system is designed with the idea that you create a new course each time you teach it. Some instructors have resisted this idea, and this has led to requests to allow them to delete students. This isn't fair to the students who should be allowed to access their work. But it does create additional work for instructors who want to re-use assignments. Perhaps a system where an instructor could transfer assignments from one course to another would suffice.

At this time we will not add a feature to upload a file of users to register for a course as that leads to lots of weird cases down the road with students registering late dropping etc.

Integration with other LMS systems

  • Add an LTI_ID field to the auth_user table. Make LTI login process identify the user record based on that ID and use the email as the runestone ID.
  • Enhance the LTI integration to support login on other systems besides Canvas
  • Allow grades to be pushed to the LMS from Runestone and vice versa
  • Allow Assignments created in Runestone to be pushed to the LMS
  • Configure the integration when the course is created

Support for Authors

github integration

  • Set up a CI service of some kind on so that authors we trust can push changes to a fork of one of our books, or a book of their very own, and the book will automatically build and deploy.

Reader Facing Improvements

  • Remove Load and Save buttons and have code auto saved/loaded -- possibly allow VCR controls for looking at previous versions of code
  • Continue to support highlighting, but allow a reader to see all of their highlights
  • Add a summary page for each user to see their highlights and go to the page with a particular highlight
  • Consider removing the user cohort code until it can be redesigned / reimplemented
  • Make code coach work


  • Add a feature like Xcode playgrounds to the activecode editor

2015 Accomplishments (and a few unfinished wishes)

In 2015, Brad Miller architected a major refactoring. Below is some history from the RoadMap for that.


  1. Cleanly separate book production from book serving
  2. Free the components from restructuredText so they can be used in other markup languages or even raw html.
  1. Morph the book serving web application into a solid service based server so that books can be cleanly served anywhere, but use all of the runestone features as a web service.
  2. Create an infrastructure where books can make use of more advanced machine learning algorithms to personalize the learning experience for each reader.

Iterative Improvements

On the writing side I see the following happening:

  • Create a separate repository that contains: thinkcspy, pythonds, common, and modules folders.
  • Move all the css and js from common into the appropriate module
  • remove the common folder
  • Make the modules folder available on pypi
  • Move modules into the RunestoneTools repository
  • Move thinkcspy and pythonds into their own repositories under the RunestoneInteractive organization
  • create a high level script for initializing a new project and building the project using sphinx. This script would be installed by pip when you install the modules.
  • Update existing modules to be Python3 compatible
  • Add the journal and other extensions from VT to the new Repo
  • Implement RSE-0001 -- Make sure the sphinx extensions work with Python3
  • Add drag and drop matching assessment
  • Add clickable area assessment #585
  • Refactor bookfuncs.js and user-highlights.js to support the components and provide a better API RSE-0002
  • Add directives to support a syllabus style page with a course schedule and links to assignments sections to read
  • Add additional metadata components to support the completion and progress tracking


  • Formally design and document an API to the ajax and login services

    • Login must support cross domain CORS authentication so resources can be hosted anywhere
    • Page login handling needs to be redesigned and made less brittle
    • Unit / Regression tests of the API must be developed to automate testing
    • Design a database schema that supports better retrieval for assessments than the current logs
    • Develop a Javascript Library to encapsulate the AJAX API
      • Logging an event
      • Saving/retrieving code
      • Saving/retrieving an answer to a multiple choice question
      • Saving/retrieving an answer to fill in the blank
      • Saving/retrieving an answer to codelens questions
      • Saving/retrieving answers to parsons problems
      • Saving/retrieving answers to short answer questions
      • Saving/retrieving answers to new image map questions
      • Saving/retrieving answers to drag and drop questions
      • Retrieving CodeCoach Hints
  • Continue to support chapter/subchapter progress tracking See RSE0004 for details

    • This should be driven by Metadata tags on each subchapter, and Javascript code.
    • Add to it so that an instructor can get an overview report for their course
    • Make the tracking Javascript/API driven. Having to run a script to parse all of the chapter files and titles is brittle and breaks the separation of book content from server. Progress tracking could/should be driven from the metadata directive, or we could develop a new directive for the progress button.
  • For instructors that want to customize their course, allow them to build and upload a course to be served by the our serving infrastructure.

    • I propose that for the new architecture instructors can simply provide a github URL for a totally customized book
    • For "normal" custom courses we make a local branch for each course when building/rebuilding the course we checkout that branch rather than copying the source. Changes to the assignments page and the new syllabus page can be tracked on the branch using git.
  • For people not using a book in a classroom setting, is there a way to harness social media to make the learning experience more communal? Can we harness the fact that at any one time there are 50 or more people on the site?

Writing Projects

  • Clean up and make public the webfundamentals book
  • Add the advanced topics chapter to pythonds
  • Incorporate new assessments into thinkcspy
  • Write introductory chapters using blockly. The idea is to start with a blocks language so that students can develop a better mental model before moving on to Python
  • Write the data modeling and querying book for CS-140

Stuff that is not as important right now

  • Add SQL as a supported activecode language