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?

In the wake of posts about Shopify's support for white nationalists and DataCamp's attempts to cover up sexual harassment
I have had to disable comments on this blog. Please email me if you'd like to get in touch.