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>
- 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)
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>
What else is there? What have you used that helped make you productive?