Best practices for mathematics lecture notes in electronic form

• produce content in content-oriented document formats, such as CNXML, DITA, or OMDoc, to allow conversion to multiple output formats (XHTML, MathML, PDF) and generation of user-specific outputs – e.g. user-specific notations (in MathML) or (canonical) MathML that can be easily parsed by Braille and Screen readers (e.g. see Archambault et al.)

• capture semantics instead of presentational features of an author's work: This best practice relates to the first one and is especially critical for collaborative distributed authoring. Authors have different preferences and conventions of notations, colour, font, and font-size. These differences can cause inconsistencies when assembling content of different authors into a new course. They should thus not be hard-coded into the content. Instead, authors should focus on the meaning and structure of the content (allowing the above mentioned conversion for various media and users).

• separate presentation from content: Different notations, colours, fonts, etc., as mentioned above, can be presented to the reader nevertheless. However, presentation and content should be coupled loosely, e.g. by marking up a word or paragraph as "important" in the content markup, and then declaring "bold" or "red" as alternative ways of presenting important content. This enables context-sensitive presentation tools to deliver the most appropriate presentation of any content to the reader.

• produce one source and reuse it as much as possible: Instead of wasting energy in rewriting materials, we should find synergies, i.e. share and reuse materials as much as possible. This is particular critical in education, many scripts and books are very similar in content.

• produce self-contained modules that can be easily reused and assembled into larger lecture components: In order to reuse and share content, we need to make them reusable and shareable. The more interdependencies we create between snippets of contents the less likely we can embed them into a new context. The reusability of large collections of content increases if they are loosely coupled. In particular, we need to refrain from using implicit transitional phrases such as "As we said earlier ..." or "In the next section...". Also, for cross-references and links between content snippets it has to be reconsidered whether they create unwanted dependencies between content snippets.

• generate and reference instead of copying content: Content reuse started when technical writers first realized that components of a document could be reused in another document. As a first approach writers copied and pasted the common paragraphs from the original document into the new document. Soon they realised that such redundancies could cause inconsistencies in their document repository that were hard to trace. To address this problem, a much better and more maintainable solution was introduced, also referred to as conditional texts: Only one file is maintained, in which all alternative paragraphs are annotated with conditions that specify when to select one of the alternatives. An alternative approach is implemented by many document representation formats. They provide sophisticated architectures that reference and link content instead of copying it. In particular, authors create a roadmap or document structure, which is technically a list of links to the content in the document repository (e.g. see Connexions roadmaps, DITA maps or OMDoc's narrative-content markup (chapter 8)). The big advantage of this approach is that changes to the central target content are immediately available in the author's document and do not need to be propagated along all the copies of this content fragment. This tremendously reduces maintenance costs and change management efforts.

• know how well-known formats have been extended semantically: Even though the above-mentioned languages are XML-based, one does not have to give up one's well-tried authoring workflows and learn entirely different languages. Jacobs University have provided invasive editing support for various "legacy" authoring environments:
  • LaTeX is supported by many authoring tools in the mathematical domain. We have developed semantic extensions of LaTeX (style files and macro collections) that allow the author to continue using these tools. This semantically enriched LaTeX can then automatically be converted OMDoc (sTeX = semantic TeX) or CNXML (CnxTeX). sTeX can be authored with any LaTeX editor; additional sTeX-specific support is available for the Emacs AUCTeX mode. More than 1000 pages of lecture notes at Jacobs University are not being maintained in sTeX. The OMDoc output (and its further transformations to XHTML+MathML) are used for interactive and adaptive presentation, whereas the PDF output, obtained in the traditional LaTeX way, is used for offline reading and printing.
    • (special best practices for LaTeX/sTeX: to be done)
  • Microsoft Office is widely used by non-scientists. By appropriate plugins, such as CPoint (for PowerPoint) and CWord (for Word), developed at Jacobs University, we can "invade" the traditional Office environment and enable it to offer content-oriented output services and output content markup (= OMDoc).

Best practice for creating interactive lectures for the World Wide Web

All best practices listed in the previous section hold, plus:

• unleash the power of interactivity offered by the presentation format: While, e.g., a picture or a video clip is reusable in the sense that it can easily be embedded into any content module, it does not respect the context of its environment. Once it has been produced, the mathematical notations, for example, that it uses are fixed. Thus, they would no longer integrate smoothly into a future recombination or adaptation of content modules. Therefore, the first recommendation is to exhaust the interactive capabilities of the actual presentation format. In a similar way as we can create context-sensitive and adaptive presentational XHTML+MathML from an OMDoc source, we can also provide certain aspects of interactivity (e.g. as JavaScript).

• separate interactivity from content and non-interactive presentation: Same as said above for content vs. presentation, the interactive aspect is another one that should be authored and maintained separately. An author who hard-codes interactivity into, e.g., notations of mathematical symbols, or a presentation process does not allow for switching interactive output on and off on demand can easily produce presentational output that is not usable in non-interactive environments, such as a browser with JavaScript disabled. If interactive behaviour is part of a document, it should fail gracefully in case the execution environment does not entirely support it.

• be prepared to interact with many diverse services; use standard communication protocols: A hard-coded interface from interactive lecture notes to a single mathematical service (e.g. an equation solver or a proof assistant) cannot satisfy changing requirements of the audience. Many standardised communication protocols for information interchange have been developed, e.g. REST or MONET. Lecture notes should make use of them to connect to services.

• more? To be done.