Last updated 1feb11 but incomplete.

Documentation Advice and Samples

To adapt this page for your own purposes, you must look at its code.

Here are a number of common problems encountered when you prepare the documentation of your project, either as a printable webpage (HTML), a LaTeX .pdf document (LaTeX), or the hypbrid (Pudding) which adds the JavaScript to translate LaTeX code to MathML in suitable browsers. These are listed in the order encountered, not in the order of importance.

HTML

This web page addresses the problems if the document is written in pure but primitive HTML. This approach is inferior to LaTeX, since the latter was invented for this purpose. The Pudding combines just enough of each to get by with some elegance.

Citations

OK, there is a lot of confusion about this issue. A citation is a mark in document, for instance a super-script 1, which refers the reader to a reference. The reference is often part of a bibliography, consisting of many more potential references than you actually cite in the document. The rule is never to put into the rerences what you don't cite. LaTeX with is BibTeX feature is the ideal way to construct your citations. But in HTML there is the internal reference tag which works quite well. Recall that a tag in HTML is anything between angle brackets. Be careful never to try using the left-angle-bracket as a less-than sign.

Jargon

Note how I have used capital letters in the above itemization. That's memorable but ugly. For example, I'm defining what I mean by jargon by using it in a sentence. There's better examples of this in the previous paragraph. In technical writing one uses a different font the first time the technical meaning of common word is used. Thereafter, you may use the word without special decoration, provided you never again use with its common meaning. For example, in VPython there is a the scene class which is used to create and manage various scenic events and phenomena. The use of "scenic" here is bad form. This sentence declares the intention of using "scene" exclusively as that class in VPython. In the above paragraphs on citations, I used "tag" early on, assuming that the reader knew I was talking about HTML tags. But I help the less experienced reader in the last sentence. In email, when all you have (or should use) is ascii characters, sometime you will see intended underlining, like this _scene_ . But that's a matter of taste. All such decorations are intended to prevent confusion.

Equations

This being a mathematics course, you can't get away with badly formatted formulas. To do it right, do it like it's in the text books. Obviously, LaTeX is preferable. But in a pinch, you could form your equations in texPad, make a picture of it, and insert it into the webpage, like this:

Code in HTML is a problem

It is very difficult to find the right trick for inserting code fragments in a webpage. It's easier in LaTeX but that's not the issue here. One surefire way is to make pictures, as above, rather than trying to do the following
\begin{eqnarray*}
x & \leftarrow & \frac{z-x}{2}\\
y & \leftarrow & y \\
z & \leftarrow & \frac{z+x }{2} \\
\end{eqnarray*}
Although this one came out OK. In general, long sections of code are best just linked to your HTML page as a plain text page. It will show up in your reader's browser looking right. For printed documentation purposes, print these links out separateley and add as appendices. You'll have to indicate that a word or phrase has a link by hand since printing out a webpage looses this feature.

Figures

There is a ton of advice in Advice for this course on the subject of making figures, and including them liberally into documents. But on was skipped, namely how to invert a bit-map image so that black becomes white, even though intermediate collors look different. Recall that a color is described by a three-byte hexadecimal like ff0aff for 255 red, 10 green and 255 blue, which is a very slightly desaturated magenta. Its inverse (every 0 becomes a 1 and every 1 becomes a 0) would be (I have to calculate a=1010, not(a) = 0101 or 5 in hex) so 00f500 which is a nearly fully saturated green. OK? since we don't really care about colors unless you refer to them in your text, this quick an dirty way of printing blackish pix is OK.

... in Windows

Just use Paint, it has an inversion feature. But I can't tell you about it here.

... on the Web

Here is an (untested) link . Please try it, and tell me how to run it, and I'll put it here 2 .

Also, note how the Image tag of HTML can resize figures so as not to take up all the real-estage on your printout.

References