mike's web log

 

Blog Search


(Supports AND)

 

Google Ads

 

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

 

Quote

There is nothing in human nature or human history to support the idea that we are morally advancing as a species or that we will overcome the flaws of human nature. We progress technologically and scientifically, but not morally. We use the newest instruments of technological and scientific progress to create more efficient forms of killing, repression, and economic exploitation and to accelerate environmental degradation as well as to nurture and sustain life. There is a good and a bad side to human progress. We are not moving toward a glorious utopia. We are not moving anywhere.

Chris Hedges



 

Navigation






<April 2014>
SMTWTFS
303112345
6789101112
13141516171819
20212223242526
27282930123
45678910


 

25 Most-Visited Entries

 

Categories

  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
  RSS
 

Blogs I Read

 

Contact

Email me
 

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 4/3/2014

Totals
Posts - 2298
Comments - 2480
Hits - 1,618,762

Averages
Entries/day - 0.58
Comments/entry - 1.08
Hits/day - 410

Update every 30 minutes. Last: 1:01 AM Pacific

 
   |  Why jane@xxx.com doesn't appear in our docs

posted at 11:22 PM | | [2] |

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:

http://xxx.com
http://abc.com

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.[1]

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. :-)

[1] Well, in security documentation (example), you always still find Bob and Alice, but that's industry convention.

[categories] ,