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

In the language as it exists clearness is not so easily won. Even under the most favorable conditions, it is exceedingly difficult to attain.

— Adams Sherman Hill



Navigation





<December 2017>
SMTWTFS
262728293012
3456789
10111213141516
17181920212223
24252627282930
31123456

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 - 12/8/2017

Totals
Posts - 2465
Comments - 2567
Hits - 2,005,630

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

Updated every 30 minutes. Last: 6:50 AM Pacific


  06:19 PM

The standard model for creating large documentation sets pretends, in essence, that the content springs from a single faceless source, namely <Your Company>. This is one of the concerns (not the only one) of a style guide, namely to define an overall tone for a content set that originates with different authors. And of course corporate-created documentation is generally not credited, and certainly not at the article level.

We're starting an experiment with changing this for our own docs. For our last couple of big tutorial sets, we're attaching author names and bios to the bottom. Here are a couple of examples:In both cases, the author info is at the bottom.

We're also going to be experimenting with adding this info to MSDN topics. Here's an example (actually still a prototype) of what that might look like:


We reckon that adding author attribution has these benefits, in no particular order:
  • Authors help develop their "brand".
  • Readers can learn to associate an author's name with a specific level, quality, and focus of work.
  • Content will get a personality and human face.
  • Readers get the (correct) impression that documentation is created by actual people.
  • Writers get public acknowledgment of their work — the company in effect puts its own stamp of approval on the writer's work, by name.
There is of course lots of precendence for this. Blogs have author attribution, obviously, and blogs have long had the benefits listed above. Books have prominent authorship, same benefits. The Patterns & Practices group at Microsoft often (not always, oddly) includes attribution (example).

It's actually interesting to contemplate whether there's any downside. The original idea of a monolithic corporate voice was probably of concern in the pre-blog days when such a voice was perceived to have more authority, perhaps. But the plethora of high-quality, attributed content on the web has probably gotten people very used to the idea that every article is written by somebody. And so it is.

[categories]   ,

[7] |