This for the Internet app nerds among the readers…
The student teams in 6.171, the software engineering class that I’m teaching this semester at MIT, are required to document their servers. By the end of the term, they are supposed to have something more or less like http://philip.greenspun.com/doc/ (doc dir for my personal Web site; rather bloated because it is based on a toolkit that is much more powerful than the features I’m using). I would have expected them to write their documents in HTML. One team has chosen to do their documentation in LaTex output to PDF. I personally hate it when information is only available in PDF, but can’t really say why. They don’t need equations or anything fancy. HTML would suit them fine, but they apparently find it easier to write in LaTex.
I always think that if a Web developer can’t write HTML by hand in his or her sleep that he or she probably isn’t very good. So the use of Microsoft Word or some other tool to author is a telltale sign of incompetence. Is this just prejudice? On what grounds can I tell these folks that a Web site should be documented in HTML?
[Fun experiment: Do a Google search for “latex” and compare the pages returned with the ads on the side…]
[Update after a few days of reflection: I think I finally figured it out. The first and most obvious answer is that documentation for Web systems need a lot of hyperlinks, and therefore HTML is better than PDF. The deeper answer is that the students don’t realize that they are supposed to be software engineers and not students. The student turns in a paper. It will never be updated. LaTex is great for that, as it was designed for journal papers that were never updated, except maybe by the author. Internet applications are fluid, however, and they get updated frequently, which requires corresponding frequent updates to the documentation. The students who decided to use LaTex are implementing their service in Microsoft ASP.NET. Eventually it will be taken over by some Microsoft certified programmer. Even supposing that they provide the LaTex source (right now they just have the PDF on the server), what are the chances that this person will have heard of LaTex or know how to use it? By contrast, if you document a Web service in HTML, you know that whoever takes it over will be able to edit it because nobody ignorant of HTML would be touching a Web service. (Of course, if the HTML was originally authored in Microsoft Word, the person needing to edit it would curse you because there would be so much extraneous garbage to wade through.)
So… LaTex/PDF good for a student turning in an assignment. Hand-authored HTML good for documentation that you expect some future programmer to take over and edit.]
Full post, including comments