OpenDSA System Documentation

6. House Style Rules

«  5. Module Authoring   ::   Contents   ::   7. Notes for AV and Exercise Developers  »

6. House Style Rules

The following guidelines should be observed when writing content for the OpenDSA project.

6.1. Content Types

OpenDSA content can generally be divided into the following types:

  • modules: written in ReST and whose source resides in the OpenDSA/RST/source directory,
  • exercises: implemented using the Khan Academy Infrastructure and residing in the OpenDSA/Exercises directory,
  • mini-slideshows and diagrams: directly embedded into modules using the inlineav directive and whose source resides in the OpenDSA/AV directory, and
  • visualizations and activities: embedded as iframes using the avembed directive, and residing in the OpenDSA/AV directory.

6.2. Algorithm Visualizations and slideshows

New content always should begin development within the OpenDSA/AV/Development directory. Once the implementation is completed and validated, then it will be moved by the project managers to a topic sub-directory.

Directly embedded content (slideshows and diagrams) should have no width set so that it will naturally expand to the page width as appropriate.

Nothing should require a width greater than 850px. This keeps all visual elements within the minimum page size enforced by the Haiku template.

The typical classroom projector provides a vertical screen resolution of 800 pixels, and that fits the limits of many laptops and tablets. Given the requirements for browser toolbars, etc., the most that you can count on for the vertical space shown for an actual browser page is about 650 pixels, so that it the absolute maximum height for any given visual element such as an AV or an exercise. It is better to stay under 600 pixels if possible, so that the show/hide button is also visible (this provides important feedback when working an exercise).

HTML, CSS, and JavaScript should all be kept in separate files. Each should pass its respective validation tools without complaint. See the developer’s “Getting Started” guide for details on using the validation tools.

6.3. Use of Gendered Pronouns in Prose

It frequently happens that some pronoun is needed, and authors are then faced with a somewhat arbitrary decision about the nominal gender. There are a number of choices that have been used, all of which appear awkward to some portion of the reading population. When possible, the best choice is to write to avoid the need for a gendered pronoun in the first place. When this is not practical, our preferred style is to use the “singular they” construction. That is, we recommend use of “they” in place of “he” or “she”, and “their” in place of “his vs. her”.

«  5. Module Authoring   ::   Contents   ::   7. Notes for AV and Exercise Developers  »