Docs: .example vs. .com

In OpenAM docs we often need to differentiate between second-level DNS domains. When writing about federation, for example, we need to distinguish among providers. In the real world, many providers use .com as the top-level domain and their brand as the second level domain. Hence we have ended up accidentally squatting on other people’s property, like idp.com or sp.com.

Read them again: idp.com and sp.com.

If they look like Internet domain names, that is because they are.

Now read these: idp.example and sp.example.

Hesitation? Actually these are the “correct” examples for use in documentation.

The string “.com” is self-evidently obvious as a top-level domain even to people who cannot say what DNS stands for or what it does. So adding something in front of .com makes it instantly recognizable: “Oh, that’s an Internet name.”

Unfortunately, we ought not use .com in documentation where we need to differentiate by second-level domain. Almost all *.com domains can belong to somebody else.

As mentioned, there is a workaround. RFC 2606 sets aside .example, .example.com, .example.net, .example.org for use in documentation. It also sets aside others like .test.

".test" is recommended for use in testing of current or new DNS
related code.

Similar story with .invalid and .localhost. These are reserved but not suited to most documentation.

Our docs do use .example.com, .example.net, .example.org. But those hide the differentiation in the top-level domain instead of where we want it in this case, which is the second level. We would have idp.example.net and sp.example.com, which is technically correct but harder to understand when reading.

The reserved top-level .example looks weird to anybody who has not read RFC 2606. I have read RFC 2606 and it still looks weird to me. idp.example in the doc is technically correct. The trade off is that readers have to slow down and think, “What the heck is idp.example? (Quick search…) Oh, these writers have read RFC 2606, which says .example is like .com, except that it’s reserved as community property so that it can be used in documentation. Okay, what was I thinking about before I got stuck on that…?”

Even though the reserved names in RFC 2606 can violate the rule of least surprise, as long as we are consistent in applying RFC 2606, then .example might be the best choice in the long term.

First, using .example is the best correct workaround that we know of at this point.

Second, using .example might actually encourage people who like the challenge of getting their heads around reasonably complex topics such as access management federation. After one stumbles on .example once or twice, one looks it up and learns what is “correct.” This once again confirms the reader’s status as a power user who knows sundry Internet arcana, turning the stumbling block into its own reward.

Third, it also makes us writers look like we know what we are writing about. We even pay attention to details like RFC 2606. (On the other hand, now that we pay attention to RFC 2606, we probably should be extra careful about the really important details, too.)

Advertisements

Leave a comment

Filed under Access Management, Docs

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s