Tech Writing Rants

Support Writers. Support the WGA.

Wed, 07 Nov 2007 03:08:08 GMT

As technical writers, we often complain (with some justification) about a lack of respect for technical writing as a profession, and sometimes even as skilled labor. Screenwriters, the people who write the scripts for TV shows and movies, and even the quips in the late-night opening monologues, face similar difficulties — and a pay structure that might seem completely alien even to contract technical writers (imagine not getting paid because your work wasn’t accepted).

The Writers Guild of America has gone on strike, picketing studios in both Hollywood and in New York City. As DVD sales now make up a bigger piece of sales, they're asking for (among other things) a royalty increase from 4 cents to 8 cents per DVD, which is still less money than what goes into the packaging. The studios are simply refusing to budge on the DVD issue, and many other issues that the WGA considers important. The studios, through their representatives the Alliance of Motion Picture and Television Producers, are attempting to paint the WGA as a club of spoiled rich writers who want far more than their fair share. In reality, a few writers are highly-paid and the vast majority of WGA members have incomes smaller than yours or mine (sound familiar?).

As technical writers, we can support our cousins in Hollywood and New York, and perhaps help them earn a little more respect for all writers including ourselves — after all, without writers, there would be nothing but news on TV. Joining the strike directly would affect nothing but our own jobs, but we can turn off our TVs and defer DVD rentals and purchases until the strike is settled. I know that's difficult for a lot of people, and I rarely watch TV anyway, but doing it — and as importantly, letting the AMPTP know about it — could have an effect.

Tell them what you're doing (write that letter and put it in the mail):

Alliance of Motion Picture and Television Producers
 15503 Ventura Boulevard
 Encino, CA 91436

818-995-3600

Contact form

Let the WGA know that you're supporting their efforts as well: mbaissues@wgaeast.org.

I may update this later as necessary. Meanwhile, take the poll and leave a comment or two.

NeoOffice to the Rescue. Again.

Thu, 06 Sep 2007 21:37:04 GMT

While I don’t have to use Word, I can’t control what other people use. That’s unfortunate, both for myself and for those people I have to deal with.

We outsourced a project that was deemed a necessary evil — and we outsourced everything, including the documentation. I could have furnished them with structured FrameMaker files, but when I said “FrameMaker” they said “huh?” So I exported everything out of markup to HTML, furnished them with PDFs of a finished project to show them how it should look, and told them to open it using MS Word. They got it mostly formatted, although the headings wrapping in the sidehead stymied them (no surprise there — Word used to have a “Side by Side” feature that could do the job, but it has been gone since Word 6.0).

After the last draft round, I suggested that they get the styles beaten into shape to make everything consistent inside each manual and across the suite of four manuals that make up this project. This they did, or at least tried to do… I think Word finally started to get the better of them. One of the manuals opened up truncated, and crashed Word when I tried to print it. I was able to open it in NeoOffice, although the headers and footers got garbled, and print it so I can at least start a content edit.

Meanwhile, they’ve cried uncle and asked for my structured Frame templates.

I know a lot of technical writers get all their work done in Word. I just don’t see how.

Heresy the Third: Metadata is for Computers

Mon, 07 May 2007 00:18:59 GMT

Heresy: An opinion profoundly at odds with what is generally accepted.

Machines work, people should think.

Heresy the Second
Heresy the First

Back in Heresy the First, Axiom 1 asserted that documentation is written primarily for people, with computers being a secondary audience (that ultimately serves the purposes of people by searching, organizing, and cataloging documents). Computers are very useful tools, but are not terribly intelligent — a computer can “read” a document, in the sense of loading it from a hard drive, but cannot “read” it the way we do. The closest a computer comes to reading is by searching for a series of bits that either match a particular pattern or appear in a particular part of the file.

Computers are very good at finding patterns, or arranging data into desired patterns (e.g. sorting); but when it comes to document handling they might need a little help. That help often takes the form of metadata, literally “data about the data.” Metadata can take several forms, some of which I’ll describe shortly.

Sometimes, metadata is simply a way to muddy the waters. “What about metadata?” comes up often when I stump for more simple, human-scale authoring systems. The proper answer may well be, “Well, what about it?” If metadata is what computers use, let the computers deal with it.

Metadata takes many forms, but these forms can be graphed:

In this graph, implicit vs. explicit metadata appears on the X-axis; internal vs. external metadata appears on the Y-axis. Let’s take a look at each pair of attributes.

Implicit vs. Explicit

Sometimes, metadata just comes along for the ride. For example, these items appear in most technical documents:

directory path

file names/extensions

title

header/footer info

terms or index entries

styles, elements, attributes, or document types

links (or references) to other documents

This is implicit metadata — information that’s part of your document, and meant for other purposes, but can be used as metadata too. Even plain text can be a kind of metadata: for example, search engines build an index based on words or phrases appearing in the document. A more sophisticated search engine could, based on keywords or phrases, provide a rough idea of what the document is about (which would provide a more refined search).

The document’s name and path can provide metadata? Why not? For example, a document’s path and file name might be:

~/Documents/Widget2000/UserGuide/Installation.odt

We can infer several important pieces of information just from this: the document is part of the Widget 2000 User’s Guide, describes installation procedures, and is an OpenOffice file. If we wanted to glean more information, knowing that it’s an OpenOffice file means we can extract the meta.xml data (we’ll explore OpenOffice files in a later post). By listing the directory, we could find closely-related files.

The document title is important — a proper title describes the document, and some search engines often weight terms found in the document title. For example, Unix “manpages” take advantage of implicit metadata; a script called makewhatis extracts the title and description from the “NAME” block to build a database of keywords that can be searched using apropos or man -k (keywords). Writing a proper manpage title can be an art — not only does it have to properly describe the content, it must contain keywords that readers would use to find that manpage in an apropos search.

In a markup context, attributes, tags, and even the document type help to describe the document. For example, the difference between DITA task and concept documents should be obvious; each topic type describes what kind of content should be found in that topic. Going deeper, attributes like class (HTML) or role (DocBook, DITA) can be used to describe parts of a document.

Links and references, as well as the document’s directory path, describe the document’s relationship to other documents — its place in the world, as it were. Even link targets (such as bookmarks or tags) can be significant, as they call out sections important enough to be referenced from other places — one could write a script to walk through a body of documentation and create a relational map of jumps and destinations (such a map could, for example, ensure that all referenced topics or chapters are included in a book or other collection).

Just as we can make a case for all documents having an implied structure (aka shared context), we can make the same case for metadata: certain items that already appear in the document do a pretty good job of describing it. All documents have metadata associated with them, whether we recognize it as such or not.

Explicit metadata, obviously, is metadata that is added specifically as metadata. Examples include:

descriptions

catalog info

properties/file info

cataloging (ToC)

search (Index)

Ironically, explicit metadata depends much more on the document format than does implicit metadata. You might specify metadata using a Properties dialog (word processors), tags (HTML), or Dublin Core (various XML document types).

The Table of Contents and Index are constructs that provide a high-level look at the entire document and a rudimentary search function.

Internal vs. External

Metadata can be either internal to the document or external. Each type has specific advantages and disadvantages.

Internal metadata can include:

tags (, Dublin Core)

document types, elements, attributes

Properties

External metadata includes:

XML Topic Maps (XTM)

file and path names

Catalogs

Search engine indexes

External metadata has the advantage of being highly flexible, and is necessary for some media (such as video). However, moving or copying a file requires changes to the external metadata; this may or may not present a problem.

Now let’s populate that graph above with examples:

Nearly any type of metadata can be pigeonholed into one or two of these four quadrants (Dublin Core metadata might be internal or external, for example).

Audience Analysis

Remember, metadata is primarily a processing aid rather than something human readers use directly. By focusing on explicit metadata, you have to write two documents: one for humans, another for computers. Even if computers are the primarily consumers of this second(ary) document, the computers are still serving human users — so audience analysis can help you to focus the work for best effect:

How will computers use the metadata? For example, you may not need to cater to popular search engines, but need to provide hooks for automated builds.

What metadata do the computers need to do the job?

How much maintenance is required to keep the metadata current?

If possible, focus on implicit metadata — it requires less maintenance, which means it has a better chance of staying current. Meaningful path and file names, descriptive titles, and proper element (or style) selection can all play a part, and often improve the readability and maintainability of your documents… and that’s the most important thing.

Mif2Go Does DITA

Fri, 04 May 2007 14:13:55 GMT

Jeremy Griffith, the proprietor of Omsys, had this to say recently:

Our latest Mif2Go release, 48, enables you to make DITA topics and maps directly from UNstructured FrameMaker files. ...

Try it yourself; the free unlimited demo is at: http://www.omsys.com/dcl/download.htm.

Naturally, I’d love to crow (squawk?) about vindication here, but I have to admit that previous attempts to bring forth structure from non-structured documents have been lacking. But Omsys has a pretty good track record; Jeremy wouldn’t be announcing this if he wasn’t sure it worked well.

I’m going to drag a PC out of the drawer and mess with this if and as I get the opportunity. If you’ve already beat on it, post a comment or email me & I’ll put it up as a guest post.

Bruce Chizen and Selective Criticism

Fri, 27 Apr 2007 15:58:43 GMT

Riffing on an FMforOSX posting from Paul FIndon.

From the Pot-Kettle-Black Olympics: Adobe CEO Bruce Chizen goes for the gold in a recent MacWorld interview:

"Microsoft, historically, has never demonstrated a commitment to maintaining a cross platform solution," Bruce Chizen, CEO of Adobe, said in an interview Tuesday in Tokyo. He cited Windows Media Player and Internet Explorer as examples of Microsoft products that are still being developed for Windows but have been ended for the Mac platform.

Of course, neither WMP nor IE are irreplaceable — Flip4Mac works at least as well as the WMP port ever did on Macs, and most other browsers work better than IE (unless an MS-addled IT drone wrote a web app you need for work). But when it comes to FrameMaker, a tech writing tool that is nearly irreplaceable without abandoning GUIs as well, Chizen’s message for Mac users is “use BootCamp.”

OK, when it comes to the flagship application suites for both companies — MS Office and Adobe Creative Suite — Adobe wins the cross-platform contest. The Mac version of Office is missing secondary apps like Access and Visio (the latter of which would be a nice thing to have on OSX), although Word works equally poorly on both platforms — which, from a tech writing standpoint, is what matters. However, the rest of Office and all of Creative Suite are (to a tech writer) merely support applications, or (in the case of InDesign) something that gets pulled out for the rare specialty document.

At any rate, Chizen has no room to complain about some other company’s cross-platform commitments.

Taking Decent Product Shots

Sun, 22 Apr 2007 19:15:40 GMT

Surprise! The release schedule was moved up to the opening day of next week’s trade show. The content is pretty much done, except for the photos — but the outside photographer can’t reschedule. “Could you take the pictures yourself?” the manager asks. “You have a camera, right? How hard can it be?” Those last five words could be a death sentence, or an opportunity.

Actually, taking decent product photos isn’t that difficult. Unlike scenery photographers, you have complete control over lighting and location. Unlike portrait photographers, your subjects won’t fidget, sweat, or grimace. Then when the pro comes in, you have a collection of shots showing exactly the angles and configurations you want — all but the most prima donna photographers will appreciate that, because they can give you exactly what you need without a lot of questions or extra work.

But there are a few things you need to have, and need to know, before you start shooting.

Gathering the Equipment

I’m going to assume you already have your own digital camera and have a pretty good idea of how to use it. If you don’t, you need to get one and learn how it works. You won’t need a digital SLR (if you have one, you probably don’t need my help!), but you don’t want the $20 model hanging in a grocery checkout lane either. I have a Canon PowerShot A80, about three or four years old now; I like it because it has a full-manual mode that lets you control everything, including flash intensity (besides, Canon did a decent job with the manual… much better than their printer manuals). You absolutely need a tripod, the sturdier the better — some have built in “bubble” levels, which can help eliminate off-kilter shots.

The next thing you need is a backdrop. Professionals often use long rolls of white paper, suspended on a pair of stands; if the paper gets torn or stained, they can simply tear it off and roll out some more. You can use that scheme if you like, or get a white bed sheet and double it up. Use a pair of binder clips and push pins to hang it on a wall and drape it over your desk. If you can, hang it up a day before the shoot to let gravity pull out any wrinkles in the sheet.

Scrounge through your desk drawers and retrieve one or two empty (or nearly empty) spools of transparent tape. These lift your subject off the table, giving you sharper bottom edges.

Digital cameras, especially consumer-grade cameras, are often starved for light. The flash helps, but can make harsh shadows and hot spots (which can be a problem when your subject is black or even dark). Get a pair of clamp lights, from your local hardware store, camera shop, or general merchandiser. They should be able to take a 75W or even brighter bulb. If your camera shop has them, get some daylight-correcting bulbs — one for each clamp light, plus one or two spares (they last only about 3 hours on average, so don’t leave them on when you’re not shooting). If you can’t find any, regular incandescent “daylight” bulbs will do in a pinch, but the right light makes a lot of difference. You’ll also need something to clamp the lights to; you can get purpose-built light stands; but cheap tripods, mike stands, or a pipe in a Christmas tree stand work. You can hold one of the lights if you have to.

Getting Ready

Make a list of what you need to shoot before you do anything else: views, angles, connections, everything. It’s really easy to skip a shot, especially if you’re in a hurry, and one missing or crummy shot will stick out like a sore thumb.

Block off some time to take your pictures, especially the first few times you do it. If you’re at work, reserve a conference room with a window if possible — remember, the more light, the better. Schedule two hours if you can; you could easily spend the first hour just setting everything up.

Setting Up

Hang your backdrop so that it curves smoothly from the wall to the desk or table. Take some time to smooth out any wrinkles (probably not a problem if you use paper) and look for shadows falling across it. Move anything casting shadows, or move the backdrop if you have to.

Set up your camera and tripod in front of your desk, with the light stands off to either side. Here’s an example, using a hand drill as our “subject.” The drill is balanced on a tape spool to get it off the desk.

This is a slight modification of the standard three-point lighting system, used both for photography and videography. In our setup, the key and fill lights are of equal strength, and we use bright room lighting for the back light. The goal is to minimize shadows rather than using them to add depth.

Look through your camera’s viewfinder and adjust the tripod and the subject so you have the angle you want for your first shot. You may need to adjust the exposure, but until you’ve taken a few shots, you won’t know how much. As a rule of thumb, with digital cameras, you should over-expose dark subjects and under-expose light ones. Each camera has its own method of making these adjustments; some have a scale (usually running from -2 to +2, and some use the traditional f-stop measurement. Check your camera manual for the details.

To get the right exposure, you need to bracket the shots. For dark objects, shoot at -0.5, 0, +0.5, and +1. For light objects, shoot at -1, -0.5, 0, and +0.5. Make a note of which order you used, so you can find the best exposure and note which one works best for that subject. Once I figured out I need to overexpose by 1/2 to 1 stop, I stopped bracketing shots because I knew it would come out right. A recently-retired professional photographer told me that if you know what you’re doing, you only need one shot to get it right.

Now that you have your game plan ready, turn on your lights. Look at the subject, directly and through the camera’s viewfinder or display. Move the lights as needed to eliminate shadows as much as possible (for portrait shots, a very light shadow behind the subject adds depth though). Look for hot spots where there’s too much reflection, and try to eliminate them (a piece of cardboard partially blocking the offending light can do the job). Now run through the appropriate exposure brackets, then turn the lights off (they don’t last long) and set up for your second shot.

Take the time to do it right, and you won’t have to do it over.

Tweaks

Few things are more frustrating and time-consuming than having to fix a photo — especially if you could have done something about it before you took the picture. But if you got a good shot to begin with, programs like Photoshop Elements or GIMP are more than adequate for minor fixes. You may have to rotate a shot ever so slightly (as little as 1/2 degree off-true is noticeable to the naked eye), and almost certainly crop it.

If you have a situation where the subject is exposed properly except in one or two spots, you might be able to fix it. As a rule, it’s easier to fix a shot that’s too dark than one where details have been blown out by too much light. If you have a situation where the only chance you had at a shot came out too dark, you might be able to rescue it by converting it to black&white before adjusting anything else.

Above all, remember that you’re using photos to illustrate your documentation. Sloppy photography is easily as noticeable as sloppy writing, and ultimately reflect on you. Your first efforts will tend to be fine for drafts; as you learn what you’re doing and improve, don’t be surprised to get requests from other departments to use your photos in presentations or even first-article marketing collateral.

Thinking Big by Thinking Small

Sat, 14 Apr 2007 04:32:09 GMT

While I haven’t traditionally been a fan of cell phones, I have to admit I like the Samsung Sync that entered my life shortly before the New Year. I’ve been fiddling with its capabilities and have a few tech writing-related thoughts about it.

If you work for a company that is involved in data delivery — and these days, most of the phone system is digital too — the Buzzword That Won’t Die is “convergence.” Cable companies provide data and phone service alongside a zillion channels of TV, and phone companies offer DSL and various video service on the phone lines. The phone companies have a technological leg up on the cable companies in the convergence race, though, through their cell phone services — but the cell phone company “charge for everything” mentality is keeping cable competitive in the convergence race. Eventually, cable companies will start rolling out Fixed Mobile Convergence (FMC) services and achieve technical as well as practical parity again.

While much of the convergence battle is being fought behind the scenes, everyone can see how cell phones are increasingly becoming pocket-sized media computers. Take my Sync, for exmple: along with the camera (video and still), voice recorder, media player (music and video, streaming or local), PDA, and web browser… they also somehow manage to cram a phone in there, too. While I have no intention of shelving my iPod (let alone my MacBook) any time soon, and some of the Sync’s features are a little clunky, it clearly points the way toward what will be commonplace in the near future: a light, portable media delivery and creation device.

If our readers could use the fruits of our labor, simply by pulling out a cell phone and pushing a few buttons, how might that change the way we create documentation? When we can document a process simply by taking a video (or a series of photos) of someone actually doing it, or by recording a voiceover, how might that change the way we create documentation?

The Sync is certainly not the last word in either portable media players or portable media recorders. For starters, a portrait QVGA screen is pretty small in absolute terms: 240x320 pixels in a 35mm x 46mm display. The Sync can read PDF and .doc (!) files with the built-in Picsel File Viewer application, but the view is shrink to fit and the application chokes on large files. Tagged PDF seems to behave a little better. Here’s examples of the video player and PDF viewer in action:

Things are about the same on the creation end. While the camera resolution is respectable — 2 megapixels — the optics are soft (as they are in nearly all cell phones) and the video resolution is sized to its screen. Audio recordings are heavily compressed (8 KHz AMR) and the mike will clip loud input.

So what’s the excitement? Simple: this is just the beginning. We’re starting to emerge from the infancy of portable media — just as personal computers had to mature before we could use them for writing, cell phones are just now reaching the point where we can even think about using them for content delivery or creation. Hard drive-based iPods are already suitable for consuming (if not recording) audio and video, and the forthcoming iPhone could make at least the delivery part nearly painless.

This is the time to start a pilot project — for example, a short installation video is feasible even for lone writers. But keep it short: partly because you’re learning, partly because your putative viewers have an attention span of roughly 3 to 5 minutes, and partly because you want it to fit in a cell phone’s limited storage. If the entire installation process can’t be covered in 3 to 5 minutes, break it up into logical pieces; for example, site selection, safety issues, and cabling could each be a separate “episode.” The video can be as simple as a slide show, with voiceovers excerpted from your installation manual. Simple is good; fancy effects are little more than a blur on these tiny cell phone screens. Save your video in 3GPP format, using a size of around 240x180.

Another possibility would be to create a special PDF, using either large text or a tiny page size. Large text on a normal page size would work better if you have graphics; the reader software can scale the pictures down and keep them legible. HTML works better for online viewing then for a direct download, since you would also have to download all the graphics.

Get a little practice now — then when you’re called upon to do it for real, you’ll be ready.

Happiness is…

Wed, 04 Apr 2007 18:06:25 GMT

An empty inbox!

XML Heresies: Nobody Expects the Spanish Inquisition!

Thu, 29 Mar 2007 03:36:06 GMT

If you’ve come to Tech Writing Rants by way of the Content Wrangler article, I hope you hang around — and feel free to leave comments. I’ve been pondering a response to the article for a few days now.

I’ll start from the bottom — because I agree with that much:

“How much structure you need will always be defined by two things,” says [Steve] Manning. “How much authoring control you need and how you plan to manipulate the content for output.”

"The first question to ask when you are looking at XML-based authoring,” says [Sarah] O’Keefe, “is, ‘What is the business case?’ In other words, how much will it cost to implement and support XML and what are the benefits?"

The phrase, “How much authoring control you need,” makes for a good question itself, but one must define “authoring control” before answering it. Maybe later.

As for O'Keefe’s question, the costs are fairly straightforward: implementation, training, and maintenance. The latter includes not only support and upgrades, but the cost of maintaining the writers — you have recurring training costs based on the amount of turnover in your department, and perhaps to get people up to speed with new components or revised interfaces. But dwelling on expenses is the easy part — as with most things related to technical writing, it’s far more difficult to measure the benefits. While a new XML-based system might deliver the promised benefits, Heresy the Second suggests that the same benefits can be obtained by other means. Neither O'Keefe nor Manning, both quoted in the Content Wrangler article, attempt to refute that.

Except for the good finish, however, I was disappointed in both the content and tenor of their responses. I’ll focus mostly on the content here, starting with specific points and moving to the general.

O'Keefe asserts:

Using structured authoring and XML, you can store information about the relationships among the paragraphs (and other components). That is,” O’Keefe says, “you can capture the fact that a title paragraph and the following five body paragraphs make up a section. You can capture the hierarchical relationships between a first-level section and the subordinate sections. You can require that a graphic must be followed by a caption. Storing the document hierarchy like this is a significant step forward, and opens up some very interesting processing possibilities.

As I wrote in Heresy the Second, non-XML documents still have an implied structure that can be leveraged simply enough, especially for high-level elements such as sections. For example, if you start with a paragraph with a Heading2 style, you can reasonably assume that it and anything following it up to the next Heading2 or Heading1 style is part of the same section. Scripting languages such as AppleScript, Framescript, or Visual Basic for Applications can express this type of construct simply enough. So you can extract a section, whether the document is explicitly structured or not — what you do with that extract is the important thing.

On the the general point. Unless I’m grossly misunderstanding something, both O'Keefe and Manning are saying that implicit structure doesn’t scale — in other words, the system begins falling apart when one involves large quantities of writers. This is an interesting argument, to say the least, but it’s obviously incorrect. The vast majority of tech writers today use unstructured authoring environments, and all of us in the not-so-distant past used them. If large groups of writers worked on enormous documentation bases before XML or even SGML existed, how did they manage changes without having the whole thing go to pieces? Either large document bases didn’t exist before XML, or O'Keefe and Manning are missing something. You can guess where I lay my bet.

For example, the Bell System Practices (BSP), a documentation set “over 40 feet long” (presumably in terms of shelf space –LK), was written and maintained from the 1920s to the 1980s. Perhaps the last 10 to 15 years of that incredible lifespan involved the use of computers at all, let alone XML (the initial draft of which appeared in 1996, long after the BSP were abandoned). The examples that I have, and those available on-line, span several decades and still manage to be consistent among themselves — the most glaring differences, in which some documents appeared to be typewritten instead of typeset, might have been due to time constraints. In other words, the info needed to be distributed before typeset copies were available — PDF didn’t exist in those days, either.

Even if we focus only on larger groups, how many of us work in such a large department? This fall, I will “celebrate” the 25th anniversary of my full-time tech writing career, and the largest department I ever worked in was during a college summer job with Sperry-Univac, back in 1981. That group numbered about 20 writers and a larger number of data entry people (keyboarding wasn’t a universal skill back then, believe it or not). I’ve spent over 6 years of my career being a department of one, and perhaps another 6 years in departments with 10 or more writers.

But let’s pretend for a moment that we all work in sufficiently large groups. We still have to ask the hard questions: do XML-based publishing systems actually make our jobs easier? Do they free us to write better documentation, or do they stifle the creativity that’s essential for human-to-human knowledge transfer? Do they make us more productive, or are all our productivity gains thrown back into feeding the system?

Can we achieve the same results with less disruption to our current workflows? I’m all for improvements, but they should be improvements.

The Electronic Paper That Would Be King

Wed, 14 Mar 2007 01:33:49 GMT

Someone forwarded a link to a Ziff-Davis “WebBuyersGuide” white paper to a mailing list this morning:

With the release of Windows Vista, Microsoft has introduced a new document format named XML Paper Specification (XPS). XPS describes the format of a new general-purpose document made available by Microsoft to facilitate the easy exchange of documents and offers an alternative to paper documents for viewing, printing, transferring and archiving. That description sure sounds a lot like PDF. So, what are the differences between the two?

This is one of those “registration required” sites, that demand all sorts of personal details that can be used to ~~spam you to death~~ target marketing messages to your needs. I passed on the registration, which was a little deceptive because the demand for details was behind an innocuous page asking only for an email address, which itself was behind a “click here to download” page.

But I’m not here to rant about trading your privacy for dubious information, I’m here to rant about technical writing and the technologies behind it: why would technical writers care about XPS? A quick Google turned up some overviews from Microsoft and Wikipedia.

I was no less dubious after reading the links. It’s not that XPS is currently Microsoft-only — it’s a new technology, and it’s only natural that Microsoft would want to get it working on their own systems first (as far as anything can be said to “work” on that side of the fence :-). The license is reasonable as far as such things go:

Microsoft freely licenses XPS technology to encourage its use as general-purpose documents. Microsoft grants a royalty-free copyright license to copy, display, and distribute the XML Paper Specification. Microsoft also grants a royalty-free patent license to read, write and render XPS Documents.

Patents. Now we’re getting into hostile territory. As far as I know, PDF has no patents associated with it (beyond the LZW compression patent, and that expired several years ago). While Adobe controls the PDF format, and extends it a little with every new version, many of us stay two or three major revisions behind to accommodate customers and end-users who are slow to update Acrobat Reader.

If you prefer to work with Linux or BSD systems, there are open-source PDF alternatives to Acrobat, at least for reading and generating PDF files. MacOSX users can use the built-in Preview application to read and annotate PDFs, where Adobe wants to charge for the latter capability. GhostScript also comes in handy when you want to do things that Adobe’s license forbids, like setting up a distilling server on your LAN. I’m not sure that even as simple a patent license as the one Microsoft is offering would allow a fully open-source XPS equivalent to GhostScript. Strike one.

The overview on Wikipedia raises another red flag:

An XPS file is in fact a ZIP archive, which contains the files which make up the document. These include an XML markup file for each page, the embedded images and fonts, as well as the digital rights management information. The contents of the XPS file can be examined simply by opening the file as a ZIP file. [emphasis mine]

While PDF security is laughably weak, do we as technical writers really need to secure our output? When I see companies like Cisco put all their customer documentation on the Web as both PDF and HTML, when customers ask for (and receive) source so they can extract some of my documentation for their training material, why would we want to make things harder on everyone (including ourselves) for no good reason? Documentation is meant to be read, not locked away in a vault. Sensitive information gets limited distribution and is protected with NDAs, after all. I suppose there’s no reason that one must use DRM, simply because it’s there. However, its presence is another strike against a fully open-source alternative.

FInally, PDF is just about everywhere, and supported by thousands of print shops worldwide. Right now, XPS is only available on Vista and XP. I expect that will change eventually — but until then, adopting XPS is restricting your audience. Strike three.

If Microsoft really wants XPS to catch on quickly, they can place any related patents in the public domain and release open-source reference code. Now that would get some attention!