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?