Technical Writing Decisions

The Python Software Foundation has given me a grant to open source my course on software engineering for scientists and engineers. I've been consulting with several people on what the course's exact content should be; the other issue I have to sort out before I start work is its format. The course will include:

  • point-form lecture notes that:
    • lecturers can use in class
    • students can skim through when they already know something about a topic </ul>
    • full-text explanations for people who ''don't'' know the topic, and won't be able to figure it out from point-form notes
    • images
      • line drawings
      • screen shots
    • programs
      • The lecture notes and text will need to be able to refer to specific sections, either by callout (O'Reilly style---cleaner look, harder to engineer) or by line number
    • sample data files
    • "generated" files (e.g. program output)
      • Must be able to re-generate all program output automatically
      • Must also get a report if/when any of it changes, so that I can check back against the text
    • supporting code
      • Makefiles (or the equivalent, if I use SCons or some other system)
      • libraries and other big (often platform-specific) things
      • </ul>

      The question is, how to prepare, store, transform, and present all of this? I bring this up here because my students face many of the same challenges every time they have to write a final report. While they don't need to mix slide content and prose side-by-side, they do have to manage images, code fragments, and so on.

      Lots of systems already exist that do some or all of what I want, and new ones are appearing all the time. (For example, S5, the Simple Standards-Based Slide Show System, uses XHTML and JavaScript to create a simple slide show.) The problem I have is that I've used all of the ones described below, and haven't been happy with any of them:</li>

      • A (modified?) form of Wiki text as the source (so that it's easy to edit and diff)
        • Generate slides and prose programmatically
        • Use a simple CGI system to display pages in a browser while editing in order to check formatting
        • Transform generated HTML/XML to create printable copy
      • LaTeX
        • Already has grown-up production tools (don't need to invent any wheels!)
        • Editing and diffing is harder than Wiki text (comparable to XML)
        • Expressing formatting right (e.g. indentation of code samples in slide bullet points) is easier than with Wiki text
      • HTML
        • Can view exactly what I'm writing...
        • ...except I don't want to: included code, point form vs. prose, etc.
        • Can CSS take care of some of the display/view problems?
      • XML (home grown)
        • Can provide exactly as much information as I need to
        • Transformation is relatively straightforward
        • Do I really want to build up my own tagset?
      • XML (borrowed from the Pragmatic Programmers)
        • Don't know if they'd let me
        • Doesn't handle slides
      • XML (DocBook or other)
        • Overkill (esp. from an editing point of view)
        • Don't know if it handles slides or not
      • WYSIWYG (Word, OpenOffice, etc.)
        • Hard to process (e.g. extract slides to one fileset, prose to another, or insert/check code samples)

      What else is there? What have you used that helped make you productive?