Wednesday, 30 March 2011
There are many times when we want to show examples that include URLs or email addresses, or when we want to show database data that involves companies or people. Basically speaking, this is not something you want to approach casually. For example, I've (recently, in one case) seen writers toss off examples that involve the following example websites:
You can guess why we don't want to include the first one in our docs. The second one does actually belong to none other than the ABC broadcasting company.
The problem is that many domains are in actual use (abc.com, who'd a thunk) or are reserved (xyz.com, myexamplesite.com) or might come into use someday because some marketing person somewhere decides that some improbable combination of letters is the latest thing. (My internet friend Nancy Friedman probably knows some oddball names off the top of her head.)
The IETF has reserved a number of top-level domains to help with this situation. Per RFC 2606, the example domain (example.com, example.org) "is recommended for use in documentation or as examples." (Other reserved TLDs include test, invalid, and localhost.)
Microsoft has gone one better and created its own versions of reserved domains. If you use our documentation, sooner or later you'll probably run across Contoso.com. This domain gets pressed into service as a fictional pharmaceutical company, a university, a newspaper, and probably many more. In reality, none of these companies exist, and http://contoso.com just points to the Microsoft.com site.
Microsoft actually owns over two dozen domains (and "companies") that we can use for example purposes. I won't list them all, but you might recognize some of them: Tailspin Toys, Humongous Insurance, Fabrikam, and the ever-popular Northwind Traders (of Access fame). A wikipedia article lists a couple more, although their list is still not exhaustive.
(An odd and somewhat related issue is that of the tempuri domain. In Visual Studio, when you create (or created, I don't know if this is still true) an XML Web service, the namespace for the XML was generated using the placeholder name tempuri.org. It might take a second to realize that this is not a Japanese restaurant, but instead reads as temp URI. In fact, you can go to tempuri.org, where the page you get to explains this. The idea is that you should point your web service to your own domain. I suspect there are many (many, many) Web services that never made any such change and still point to tempuri. No matter; it all still works. This isn't really an example URL as such, but it does fall into the realm of more-or-less safe URIs, since it's reserved, sort of.)
Anyway, we have a similar issue with names and email addresses. In the way-old days, we used example names as opportunitites to slip into the doc sets the names of our kids or dogs or whatever. (This was back in the days when it was popular to include Easter eggs in the software, too.) The legal people at Microsoft frown on this sort of thing. Instead, some years ago they invited people to submit their names (first and last) to be used as example names, which required the submitter to sign a release that Microsoft could use the name in perpetuity, blah-blah, whatever the legal requirements were to let the company use the names freely. We now have a list of several hundred names to use as we like. Because they're real names, they vary a lot, so it's not just Sally and Joe and Mary over and over.
I occasionally get into a, um, discussion about this with a writer who wants to use his or her own name. This would seem to be innocuous enough (and we all did it in the past), but this just underscores that the writer isn't understanding what it means for someone to sign a release. You always have to imagine the worst possible scenario: writer uses his own name in a popular document; writer ends up leaving the company on bad terms; writer decides that the evil company must be punished, hires lawyer, brings copyright suit for use of un-released name. I have no idea whether this is even legally feasible, but it's absolutely not feasible if we stick to using only pre-approved names. And thus we insist.
We have an entire infrastructure for this at Microsoft, including crack legal talent that's sorted this out for us. Even if you are not able to avail yourself of something similar, you should at least draw up some conventions for how to handle fake names and URLs in your documentation and not leave it up to the whims of whoever's writing the examples. If you do, I can almost guarantee that you'll end up with, if not xxx.com, the name of someone's dog in your doc set. :-)