Crediting documentation - mike's web log/comments

New comments for this entry are disabled.

December 08, 2011 | Crediting documentation | 22701 hit(s)

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.

Nicole 08 Dec 11 - 6:43 PM

Well, I love this idea in principle, since it would certainly help me. Two issues:

1: Issues related to updating topics: At what level of rewrite does the byline change to the updater? Who decides? Will this cause groups to not update topics because original authors want to protect their bylines?

2: Issues related to co-authoring: At what level of help does a writer get added to another writer's topic's byline? Who decides? Will this cause authors to stop collaborating in order to protect their bylines?

Mark Baker 08 Dec 11 - 8:20 PM

Hi Mike,

I think it is really cool to see this happening. Interestingly, your post mirrors a discussion Tom Johnson and I had about a month ago in the comments on his post, The Importance of a Personal Face (http://idratherbewriting.com/2011/11/01/the-importance-of-a-personal-face-on-halloween/#comments).

There is just one caveat I would make here. I think that this is absolutely the right thing to do if the writer is not simply the scribe, but actually the subject matter expert who has written the piece out of their own knowledge and experience. It would send a very false not to mark a piece as "by X" if X was simply ghost writing for someone else. The byline should go with the idea, not the scribing.

As I noted in my conversation with Tom, in tech, reputation is personal. If you put your name to something, you are claiming ownership of the ideas, not just the words. People will expect you to be able to back up any words that appear under your byline, and it will be pretty embarrassing for both the company and the writer if customers find out they can't.

Django Wexler 08 Dec 11 - 8:43 PM

The only downside I can think of has to do with when content changes hands. As an MS author I "own" an enormous amount of material, only a tiny fraction of which I've even touched, let alone written.

So if you put my name on everything I own, then a) I'm getting credit for whatever good stuff is now out there under my name, and b) I'm getting blamed for whatever BAD stuff is out there under my name. If you don't put my name on everything I own, what does get? Just new stuff that I write? How much of a change/addition is required to an old topic until I can put my name on it?

The basic problem is that many topics (and reference docs) on MSDN are not so much "written" in the same way as, say, a blog post, but more like "curated" in the manner of a wikipedia article. Some of the older topics I own have had literally dozens of writers making hundreds of changes over years, so establishing "authorship" is not an easy thing!

Kent Sharkey 08 Dec 11 - 9:09 PM

An utterly, utterly excellent idea! It's about time that this credit be given to the nameless, faceless (well, not in person) people who have saved so many so much time over the years. Well, and blame, when it is due (like whoever decided to put code as images in http://msdn.microsoft.com/en-us/library/ff512385.aspx).

As for rewrites, it can be like when books are revised: if there is still enough contribution by the original author, their name stays, otherwise, "Last one to touch it, owns it."

mike 09 Dec 11 - 7:56 AM

@Mark: For the content we're involved in, the question of expertise shouldn't be an issue, I don't think. For example, Rick, who's the author of the MVC tutorial above, is also a moderator on the forum for that technology.

The title for writers in our division is "Programmer-Writer," and they're serious about the first part of that title. (A discussion for another time is how serious they actually are about the second part, haha.) Obviously, documentation is created with the close cooperation of the development and test teams, but if there's a name on an article, it's definitely the work of that person.

Anyway, that's the case so far. Which leads me to point 2 (also for you, @Django), which is that at this stage, author bylines are both optional and manual. If we want them, we're free to put them in, but they're not required. We have to stiff them in by hand; they're not slurped out of the document's metadata, for example. If they were, it could lead to the problem that Django is alluding to (I think?) -- whoever happens to be assigned to a topic would show up as the "author." In our world, authors can instantly "own" thousands of legacy topics if they're reassigned to a mature feature area. That would definitely dilute the concept of authorship to the point where it would be meaningless.

I think that as long as the byline is optional, and if it's used properly, it's overall a force for good. If it just becomes a Certificate of Attendance, then yeah, who cares. :-)

JaAG 09 Dec 11 - 12:15 PM

Including the reviewers is something I've never thought about but approve. Reviewing is usually a thankless job. Cap tip to my all time fav reviewer, Jim Daly.

Mark Baker 09 Dec 11 - 12:25 PM

I don't see crediting the author as a way to make the author feel good. The author gets a paycheck, and whatever perks and personal recognition the company sees fit to bestow, to make them feel good.

The point of crediting the author is to improve the company's relationship with the customer base by putting a personal face -- a trustworthy and knowledgeable face -- on the company and it's products.

There are good business reasons to do this, and it should be done for business reasons, and only in a way that promotes business reasons. It's not about rewarding thankless tasks, but about building customer value.