About

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

Read more ...

Blog Search


(Supports AND)

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

Here is a thing to carve in pokerwork and hang over your typewriter. "No one will ever complain because you have made something too easy to understand."

Tim Radford



Navigation





<July 2024>
SMTWTFS
30123456
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  
  RSS  

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 6/2/2024

Totals
Posts - 2654
Comments - 2677
Hits - 2,680,687

Averages
Entries/day - 0.34
Comments/entry - 1.01
Hits/day - 348

Updated every 30 minutes. Last: 8:24 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] |