Skip to main content


Which documentation standards do we decide what to teach students, and does it matter? In this post, I'm going to explain why I teach students in my technical writing courses XHTML for Web design instead of HTML5.

My suggestion is to teach what works most consistently across computing platforms, knowing that the standards of today will be replaced. Documentation file formats and coding habits should adhere to standards because one of the goals of technical documentation is that it be easy to update and revise at a later date.

Teaching documentation, therefore, should include teaching the ideal habits for technical writers and documentation designers.

Consider HTML and XHTML. Long before standards bodies, such as the W3C, approve and finalize any standard, experience teaches us that the browser developers will have already implemented a mix of whatever is coming — and each browser will be an incomplete and incompatible mess. I still remember trying to get basic features to work in Netscape Navigator and Internet Explorer.

If you teach about ePub formats, I would teach ePub 2.x and not the unsettled ePub 3.x standard. If you teach HTML, I'd stick to HTML 4.01 Strict, and I'd introduce students to XHTML 1.0. These standards date to 1999 and 2000; as a result they are stable and somewhat predictable. No, it isn't the cutting edge of HTML5 goodness — but moving from HTML 4.01 or XHTML 1.0 isn't going to be a problem for students.

I am currently revising some Web pages to meet the "XHTML 1.0 Strict/CSS3" standards. The choice to use XHTML 1.0 instead of HTML5 was not simple, especially since HTML5 is the shiny new trendy standard. The problem with shiny new standards is that they don't work well with older browsers — and plenty of people are still using older versions of Internet Explorer. Plus, HTML5 seems to be something of a moving target because no browser offers full compliance. More annoying than HTML5 is the need to use various CSS tricks to make a page look good on a variety of browsers.

One reason I lean towards XHTML is that the habits you develop while coding XHTML are "better" than what most HTML4/5 developers seem to practice. I believe it is important to teach students good organizational, design, and implementation practices. HTML is, bluntly, far too tolerant of bad coding. XHTML 1.0 Strict requires consistency, because it is an XML implementation.

HTML is based on SGML (Standard Generalized Markup Language), but only loosely so. Most browsers don't actually use the SGML Document Type Definition (DTD) for HTML — they parse the page based on whatever HTML is hard-coded within the browser. Badly formed HTML code, with missing closing tags and deprecated tags won't break most browsers. It's not a bad thing that browsers are forgiving — much of the Web would cease to work if browsers halted when parsing bad code. Still, it is annoying to know that your "DOCTYPE" declaration is generally meaningless.

XHTML is XML-based. Yes, XML is based on SGML, but unlike the forgiving HTML parsers that tolerate errors, XML editors and validators often demand that the developer fix errors. (You can "validate" HTML or XHTML, but I've found HTML5 "validation" is something of a joke. Because almost any code is okay, the validators find few errors.)

There is talk of XHTML5, which is something I would appreciate — as long as it doesn't allow the bad habits tolerated by HTML. The debates about calling the standard XHTML 1.5 or XHTML 2.0 seem to have been resolved, with standards bodies such as W3C and WHATWG agreeing that it would be logical to align HTML5 and XHTML5. It seems to have confused people that XHTML 1.0 was, approximately, an XML implementation of the HTML 4.01 standard. (XHTML 1.1 was beyond confusing, for reasons that I won't discuss here.)

Some students will wonder why they should learn XHTML 1.0 instead of HTML5. You should explain that the consistency of XML coding will help them in a number of ways that HTML5 coding does not. For a summary, I suggest this article:

I consider the following points the most important:

XHTML, being XML-based, gives students a foundation for other XML-based document formats. Everything from Apple's system preferences to Microsoft Office documents are now stored in XML formats. Learning XHTML is a good, clear way to learn about XML coding.

XHTML, XSL, XSLT, XPath, and XQuery work together to enable flexible output formatting. If you want to be a documentation expert, you need to understand databases and structured output.

While my technical writing students might not appreciate why I'm using XHTML, even after I explain what XHTML is, they will be learning better habits and a skill that is essential in the data-centric world of technical documentation.

Suggested links:


Popular posts from this blog

Slowly Rebooting in 286 Mode

The lumbar radiculopathy, which sounds too much like "ridiculously" for me, hasn't faded completely. My left leg still cramps, tingles, and hurts with sharp pains. My mind remains cloudy, too, even as I stop taking painkillers for the back pain and a recent surgery.

Efforts to reboot and get back on track intellectually, physically, and emotionally are off to a slow, grinding start. It reminds me of an old 80286 PC, the infamously confused Intel CPU that wasn't sure what it was meant to be. And this was before the "SX" fiascos, which wedded 32-bit CPU cores with 16-bit connections. The 80286 was supposed to be able to multitask, but design flaws resulted in a first-generation that was useless to operating system vendors.

My back, my knees, my ankles are each making noises like those old computers.

If I haven't already lost you as a reader, the basic problem is that my mind cannot focus on one task for long without exhaustion and multitasking seems…

MarsEdit and Blogging

MarsEdit (Photo credit: Wikipedia) Mailing posts to blogs, a practice I adopted in 2005, allows a blogger like me to store copies of draft posts within email. If Blogger, WordPress, or the blogging platform of the moment crashes or for some other reason eats my posts, at least I have the original drafts of most entries. I find having such a nicely organized archive convenient — much easier than remembering to archive posts from Blogger or WordPress to my computer.

With this post, I am testing MarsEdit from Red Sweater Software based on recent reviews, including an overview on 9to5Mac.

Composing posts an email offers a fast way to prepare draft blogs, but the email does not always work well if you want to include basic formatting, images, and links to online resources. Submitting to Blogger via Apple Mail often produced complex HTML with unnecessary font and paragraph formatting styles. Problems with rich text led me to convert blog entries to plaintext in Apple Mail and then format th…

Screenwriting Applications

Screenplay sample, showing dialogue and action descriptions. "O.S."=off screen. Written in Final Draft. (Photo credit: Wikipedia) A lot of students and aspiring writers ask me if you "must" use Final Draft or Screenwriter to write a screenplay. No. Absolutely not, unless you are working on a production. In which case, they own or your earn enough for Final Draft or Screenwriter and whatever budget/scheduling apps the production team uses.

I have to say, after trying WriterDuet I would use it in a heartbeat for a small production company and definitely for any non-profit, educational projects. No question. The only reason not to use it is that you must have the exclusive rights to a script... and I don't have those in my work.

WriterDuet is probably best free or low-cost option I have tested. It is very interesting. Blows away Celtx. The Pro version with off-line editing is cheaper than Final Draft or Screenwriter.

The Pro edition is a standalone, offline versio…