And a class award for best documentation might help motivate the teams.

I think that you should consider forcing them to (1) write their documentation in strict, semantic XHTML, (2) format the document using CSS, and (3) publish an RSS feed that lets users know when their content has changed. The students will learn a lot by doing this and they can write converters from XHTML into any format their hearts desire. Ultimately, being facile with XHTML, CSS, and RSS will be a lot more useful to them than becoming experts at LaTeX.

One advantage of hand-crafted HTML over Word or text documents is that it feels like programming. A programmer hates writing documentation – but maintaining a program is something else again. A wiki is even worse – it feels like using a version control system. Programmers hate version control even worse than documentation. At least you can ignore documentation – but a version control system usually lies right in the path of getting the job done.

We’re using the Instiki wiki, and it’s working beautifully. One of the reasons people don’t document enough is that it’s inconvenient. The wiki reduces resistance. It’s also easy for our non-technical staff to use, and they do need to document their work and processes. The wiki gives them a searchable, hyper-linked, versioned system that’s about as easy to use as a word processor.

For more elaborate organization we’re looking at Moin, which offers embedded macros with which you can bring chunks of text together, generate local TOCs, etc. We’re also looking at Trac, which is a wiki-based front-end to Subversion. The Ruby Rails developers use Trac, and it’s written in Python. So maybe we all *can* get along, after all. (Nah.)

I’d like to second the suggestion for using Markdown. You get a readable plain-text version of whatever you’re writing for free, and it saves gobs of time, and typing for example backquotes instead of >code< all the time invites lazy types like myself to add rich formatting.

Bob: Certainly none of the students are using AOLserver, Tcl, or ACS. I doubt that any of them have heard of any of those systems. The students are 21 years old. The Doxygen system you mention does not seem to cover the kind of information I want them to write, which is generally much higher level and includes an explanation of why they wrote some code in the first place. http://philip.greenspun.com/doc/chat is an example of what I’d like to see for a module, for example.

I am not sure if I agree that either hand-crafted html or hand-crafted LaTeX is the best approach when documenting code. The inevitable problem arises as the code base gradually diverges from the documentation until they soon end up describing quite different things.

I am personally in favour of using tools like Doxygen which covers many, but not all programming paradigms. Can we assume these students are working on openACS using tcl? I love tcl to death, but Doxygen may not be too helpful here. Perhaps it does suggest the need for an openACS documentation tool which would allow students (and “real” developers) to document their code in a formal way which would allow consistent documentation to be “generated” in either LaTeX, pdf, html (or even odt) depending on the requirement.

Okay, I finally figured it out and updated the main posting. PDF is bad because it can’t be edited. Computer programs change. Internet applications change even more rapidly than other computer programmers. A native HTML document means that the programmer taking it over and updating it will have the source code. Any programmer who is working on a Web site will know HTML. That’s why all docs have to be in HTML (except maybe some figures/images).

+1 on letting them use a wiki. A couple open source projects I’m on switched to doing docs completely in wiki, and the resulting increase in documentation is incredible. In many ways wiki is what html was _meant_ to be, a very simple mark up language that anyone can use to make a web page.

As for the original question, there is a _bit_ of grounds for prejudice against an html generation tool, since if people are using different generators then diffs in version control won’t align right. But letting them go latex -> html with a generator seems valid, as long as the team is aligned on everyone using latex, storing the sources in version control, and having the build always generate new html docs from the latex sources. Latex -> pdf seems silly, as it’s just annoying on the web. Yes, you can do links, but for me it opens them in ie, my non-default browser.

For what it’s worth, I agree with the idea that if the documentation is expected to be less than 5 pages, contain hyper links, have no need for fancy equations, and need to be viewable in the same browser as the rest of the website HTML is the right tool for the job.

It sounds like you are not asking the students to write a thesis, or any paper which will end up published in the dead-tree world but website documentation which will need to be easily viewable on-line from within the same environment as the website they are documenting, so require the work to be in a format that meets these requirements. I am not saying that they need to write all the HTML by hand, as there are plenty of tool available to convert from La Tex into HTML (a few of which have been mentioned in these comments already.)

Finally my personal angle…I hate clicking on a link in a website that opens a PDF. Loosing control of my computer while the PDF viewer loads, is totally unacceptable, personally I think that the place for PDF docs on a website is to store papers which require that format such as technical papers, documentation which is expected to be printed, etc… basically use PDF when you want the user to print the document, and HTML when you want the user to view it on-line. The thought of clicking on a link which claims to be website documentation and then loosing control of my computer until the PDF viewer is finished with it is unacceptable and is enough to stop me from using one site in favor of another where the developer was willing to spend a little extra time to create the documentation in a way that lets me read it while still doing the 5 other tasks I am trying to perform with my computer. The point is, think of the users of the site, are they going to want/require the documentation in PDF or will they get as mad as I do while waiting for the PDF viewer to load.

So in summary, I vote to make the requirement HTML. Turning the final work in as a PDF is like using a screw-driver to pound in a nail, it’s the perfect tool to do a job…just not this one.