About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

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

Political freedom cannot exist in any land where religion controls the state, and religious freedom cannot exist in any land where the state controls religion.

— Samuel James Ervin Jr.



Navigation





<January 2018>
SMTWTFS
31123456
78910111213
14151617181920
21222324252627
28293031123
45678910

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  
  RSS  
  RSS  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 1/15/2018

Totals
Posts - 2475
Comments - 2570
Hits - 2,015,323

Averages
Entries/day - 0.47
Comments/entry - 1.04
Hits/day - 379

Updated every 30 minutes. Last: 9:59 AM Pacific


  11:57 AM

We got a customer comment the other day observing that we had a contradiction in our documentation. In one topic, we note that the maximum size of a particular document type is 128K. In another topic, we note that the maximum is between 2K and 10K (dependent on some technical details).

We investigated. The results were a little surprising: seemingly paradoxically, both topics were technically correct. The 128K limit pertains to a transport limit — it's the largest document that will be accepted for upload. The 2K-10K limit is a business rule that is invoked later when the document is being saved.

It's like a 10-ton truck trundling down a road. Maybe the weight limit on the road is 50 tons. However, if the road crosses a bridge with a weight limit of two tons, that's the effective limit for the whole road.

We contemplated various ways to fix this problem. A complicating factor was that the text about the 128K limit was generated into the documentation automatically. (By a JavaDocs-like process, if you're curious.) The particular conundrum was how to explain, yet dismiss, the 128K limit in a way that made sense to the customer, since for the most part there is no practical circumstance under which the clearly documented 128K limit actually made sense.[1]

A lesson (or maybe just observation) is how hard it is to write documentation in a holistic way. It's quite possible that the two topics were created by different writers at different times. Each topic is, as noted, "correct" in a narrow way. It's a real challenge to try to understand the overall customer experience. This is especially true for API/reference documentation, which is focused on a very tiny slice of the whole — a little like writing a dictionary definition and trying to anticipate all the contexts in which people might use a word.

It's a hard problem, but it's one worth trying to solve. In the end, the customer doesn't really care that the 128K limit is "technically correct" or that the topics were written in different contexts, blah-blah. The end result, as we experienced ourselves, is that the customer is confused. And whatever the difficulties of trying to coordinate far-flung pieces of documentation, surely documentation that leaves a customer with worse information than what they started with has to be a big incentive to try.

[1] The limit was set high for a legimitate reason; the only thing I'll say about that is that the 2K to 10K limits are set by business rules, not physical constraints.

[categories]  

[2] |