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

If proper usage gets in the way, it may have to go. I can't allow what we learned in English composition to disrupt the sound and rhythm of the narrative. It's my attempt to remain invisible, not distract the reader from the story with obvious writing.

Elmore Leonard



Navigation





<May 2022>
SMTWTFS
24252627282930
1234567
891011121314
15161718192021
22232425262728
2930311234

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 - 4/10/2022

Totals
Posts - 2640
Comments - 2648
Hits - 2,472,669

Averages
Entries/day - 0.38
Comments/entry - 1.00
Hits/day - 358

Updated every 30 minutes. Last: 12:47 PM 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] |