Content Musings

Attention span compromised

I admit it. My attention span has been compromised. How else can I explain that I won't read any blogs that look like MSDN content-- all words and, well, more words.

I just won't do it. And, that cuts off a lot of content. I am, by no means, an early adopter. I still don't use  Channel 9 , and I do use a Pocket PC. But content that is devoid of any other kind of visual information is not just tiring but also less effective. As a wordy guy this causes me chagrin but I'll get over it.

I can only guess that this is some deeply profound biological change in my brain that marks the onset of something, what's the word, not good. But even then, I must try at least to keep apace of the change. Don't I?

There are pithy blogs that can get away with just words, clever words, but it's hard to be pithy about work flows, agile vs. formal process, and something like Share Point. I better walk the talk and pump up the content.

The choices are not limitless. In order to be more effective and catch a stray reader now and then, I'll need words (still useful), white space (still underrated), video, audio, and pictures, right. That's all of it. Or am I leaving something out?

Clearly, I still have a not way to go.

Take this blog and repurpose it

It is about time I repurpose this blog. After working on a blog for almost two years, the facts speak for themselves. I can see that my blog will never be prolific. It won’t be a daily blog you have to check. I tend toward the more in depth treatment of a given subject. I’m okay with that, I accept the consequences of lower readership.

However, I still like writing it.

Since my last entry, I have changed teams. In fact, I have even changed divisions. This is a big deal. The change provides a nice backdrop for changing direction with the blog. In fact, I’ve changed the title to the pun-laden Content Musings to symbolize the change.

If you have never worked at a large company then maybe it is hard to grasp a change of divisions. It isn’t quite as significant as changing companies. No change in benefits; no change in salary, etc. However, the shift in perspective has certainly been more significant than I expected. And, the process of the change, the job interview and preparation are similar.

The work itself, to date, has not changed much on the other hand.

Facts: I worked in the Developer Division for almost 10 years, known as Server and Tools Business. Now I work over in Office, or Microsoft Business Division. As a contractor, before any of this, I worked in Windows in an adjunct part of the company then called the Win32 SDK, renamed the Platform SDK, to now become the Windows SDK. There are still places like Games/XBox and Mobile, where I have almost no idea what happens in that part of the company.

I look forward to this challenge. I’ve yet to explore exactly what I can say about my specific job publically. At least for now, the blog will continue to be less about the actual product where I provide content and more about how the work gets done.

Some might say I’m a process guy. That’s fair enough. Creating content as opposed to the underlying product seems to drive that point of view.

The other fact that invigorates me about my blog is being joined on this team by David C. as I’ve called him in a previous post. David is another process guy. Without his type of input and thoughtful provocation, I probably wouldn’t write a blog. He’s even more of a process guy than I am. He’s an Official process guy, a certified Scrum Master with Agile and Lean street cred. That’s right. You heard me. There’s an Agile Street and there, David’s the Mayor.

Please continue to send me mail and comment if you like. I haven’t gotten lots of comments in the past but I do welcome them and engage them.

P.S.      Here are some subjects I’m considering for the future: Editors – and the relationship with a technical writer; Requirements-driven content; Content Publishing as a job choice; and the role of Attitude at work.

P.P.S   The astute student of American culture will recognize the paraphrase in the title of this post as a Johnny Paycheck reference. I blame my father for any knowledge that I have of country music and NASCAR. Thanks, Redsy.

GTD, Kanban, Scrum, gets all the credit

The funny thing about any new methodology you might try is that the method seems to get all the credit in the end.

Here's a paraphrasing of  conversation with some co-workers. One of them is trying to convince his team to avoid a bumpy road traveled many times: tracking work hours against estimates. Yes, experienced content publishers, writers, editors of all kinds, I said tracking hours. Please don't turn the page yet.

You can switch to Kanban, GTD or hours tracking. It’s the fact that when facing a continuous, repeating problem that someone makes the choice to use an appropriate methodology. The people make the change. Yes, as a consequence the process was changed, too, BY PEOPLE. The people should get the credit.

In fact, the universe doesn't care at all what you do or what method you choose. Dare I say, it doesn't even care if you make anything.

On my last team, we made the decision to switch to Kanban. We gave it consideration and openly discussed the merits. We had some contentious discussions about whether it really is a “pull” strategy for example. And I think, for that problem, we chose well.

Plus, we had experienced writers who had used various systems comment on the various merits of those ideas. We stone-cold knew our problem. That’s a good place to start. An idea like tracking hours does not address the problem we had.

I might add our manager let us do it. He gave us the autonomy. That’s a rare commodity. It can be based on confidence-inspired trust or blind faith. Either way, we did it.

Mr. Kanban meet Mr. Constraints

Our team has been using a kanban system for several months now. We switched from a modified scrum. One of my colleagues, David C, is a dedicated professional who finds project management fascinating. Please, do not hold that against him.

David C is the prime mover of the ideas of another David, David J. Anderson, to our team, e.g. kanban. The more I read on Anderson's blog, the more I see that most development process improvements might be, insidiously, directed at management. This conclusion might seem obvious to the more cynical reader. 

I might be boiling down this post to the point of losing its essence, but here goes.

There are things that a worker can control and stuff you (a worker) cannot. The stuff you can control (the process our kanban maps) are worth trying to improve using work focused techniques such as the Five Focusing Steps. This is all common sense stuff to an actual worker.

The other, less obvious point to me is that the stuff you can't control largely falls in the bucket of policy. This is the Office Space stuff like TPS reports (American cinema reference). If you have a policy the prevents anyone from using a new build system, then you should not bring a technique such as the Five Focusing Steps to bear on it even when it creates a bottleneck. In fact, there is nothing you, the worker, can do on the assembly line to fix that.

It would be like a guy at Toyota saying that they need to stop using Toyota robots and start using Ford robots or something like that. Or it would be like trying to get US manufacturers to use the metric system. It's not a process, you-can-control action; it's a policy, you-can't-control decision.

Passion

The subject of passion enters a lot of discussions at Microsoft. You hear this in the form of encouragement about your career. Do something you're passionate about and you'll never work a day in your life. To writers: Find what you're passionate about and write about it.

I find all this somewhat odd.

Imagine you were a lexicographer - a dictionary writer.  Do you think it would be okay to only write about the words you were passionate about? Or maybe you'd just do a good job on the words you are passionate about? It seems like it is a professionals job to write fine dictionary definitions about all words, even set and plus. Should we neglect prepositions? or wait 'til we find a passionate preposition lexicographer? Something tells me that might not be cost effective. Perhaps we'd just expect a competent professional to do a good job with all words.

To be honest, I feel for the words and documents about subjects that don't inspire passion in a writer. I feel compassion for the poor subjects that are and will always be ordinary. Some will be useful and some will be mostly ignored.

In fact, I might suggest to the aspiring writer that she or he find the most boring, mundane thing and try writing about that. If I were a business ower, I think I would pay good money for that.

Minor grammar revisions after initial post - yikes.

Ambiguity

I've been having two thoughts lately about my blog. First, I need to change its focus so I write more; Second, I need to write more.

Well this post will be the kick-off to the focus changing. I don't write on an SDK these days so the title is a bit of a misnomer. Also, I used to work with an editor who inspired me to write in my blog, Dave Baldwin. Dave also kicked me in the pants recently by saying, "Hey, dude. You ain't writing in your blog. Write something." Well, he said something like that. More polite.

I've had this thought in my mind for awhile. At my employer, we celebrate the ability to "deal with ambiguity." While thinking about this over my second cup of coffee, I decided that there is really only one way to deal with ambiguity: reduce ambiguity. That is, have less of it. Unvague. Increase clarity.

If you wanted to improve your ability to deal with it, what would that look like? I'm going to hit you with a stick in the dark. It will hurt so you should find a way to not get hit by the stick. It will be at random intervals and from random places. You won't know when or how I will it you. In a word, it will be ambiguous. Now, deal with it.

I'm sorry but I don't see any way that you can improve on your dealing with it. You can complain less about it. You can steel yourself for the inevitable pain, but that's not exactly dealing with it.

If you had to ship something, but no one tells you the deadline. The deadline is ambiguous. I don't see dealing with that as a good solution. Why don't we hide all the mailboxes while we're at it. You can mail stuff; it will just be harder.

Thinking like a user is hard

To develop effective documentation for users, the writing team should understand the experience of the user. This is harder than it sounds. Writers, like anyone who works in software, build up a tolerance for the vagaries of software was it moves through development.

Think of the old days, when you would have to orient the rabbit-ears on your TV set and hold your arm out to get the UHF channel that had the ball game. At some point, you stop thinking this is weird. (For you kids who don't understand this, well, download some music or something.)

Re-visiting this user-centric model, requires the writer to identify when s/he stops seeing the idiosyncrasies of beta software. For instance, oftentimes, you have to perform special weird instructions during the installation of a product that is still in beta. But that's not going to be the user experience. Well, it better not be!

So writers and editors go to the trouble of re-focusing periodically to get a more user-centric viewpoint. They re-organize the Table of Contents. Or, go 'off-site' to do some new fangled training exercise. These, and other ways of seeing the user experience, are quite valuable though they often seem a little odd at first. And like a lot of things in corporate life, the exercises seem like an unnecessary re-hash of similar exercise of the past.

Orienting the documentation back towards the user is often a corrective measure. Why is it necessary? It's necessary because the people creating the software, the product team, are the primary source for the material. After all, they just made the thing. They are the only experts. And as the writer moves along in the application life cycle, with the application, s/he gets sucked into the orientation of the developers, testers, and other fine people that make software.

Posters

Our team just started one of theses corrective exercises. We got the idea from another writing team of a different product. We are trying to create posters that describe the complicated process of using Team System to develop software. I think the goal of the posters is noble, i.e. re-orienting the documentation and the writer to the user-centric viewpoint.

Some people are really good at seeing this kind of grand vision. Others do not come to it easily. Some are good at creating it. Teams usually have a mix of people and skills. In fact, as long as teams effectively co-operate, avoid becoming territorial, and head towards a common goal, the variety of ways of thinking can help produce better results.

It's hard to stop thinking about old features and new features when the product team's reason-for-being is that singular pursuit. But that's what they should be doing. They need to make sure that all cases are considered not just the primary ones. And while users want reliable and high quality software, most experience the primary scenarios and not all the odd ones at the margins.

The user's actual view does not contain features that don't exist. Imagine I handed you a cork screw but you'd never experienced wine. Even if I explained how to use it (the corkscrew not the wine), you'd still be scratching your head. A picture (maybe from a poster) might be a good way to provide the user with a way to fit-in new feature knowledge with the existing user-centric models that already exist in their heads.

For me, the poster exercise hasn't yet coalesced, but sometimes that takes time. I suppose it's possible that poster exercise just won't work for us. I think the other team said that it actually took months to gel so we are just starting out. However, it has reminded me that our job, providing help to users when their understanding is breached, is more user-centric and less product-centric. But it's harder than it sounds.

Evolution of a job title

While the title of this blog is SDK writer, I do not write for an SDK team at this time. My job responsibilities have evolved. Presently, I write Help documentation for our product, Team Foundation Server. My job title at Microsoft is Programming Writer, a title that my division seems to hold quite dear. I have never liked this job title. No one really knows what the job title means except those who do the work. That kind of "priesthood" approach to anything rubs me the wrong way. Plus, it's inconvenient in social introductions.

My title is the same but my work is changing. But all this change got me thinking: Why would an SDK writer think that he or she is different than any other kind of writer?

Usually, different names indicate a perception that the writing is for a different audience or requires different skills. It does not mean that we ought to take short-cuts.

Let me borrow an example from another discipline. We might have a bunch of tests that were developed to provide good code coverage during development or we might have some code that we used in a demo for upper management. Shipping that code might be helpful. That code might be better than no code at all, but it would definitely be a short-cut. Most of the time, code like that does not represent a good customer scenario.

What I am discovering by not being an SDK writer is that most of the documentation needs are the same. The details change, but the requirements do not change. Geometry does not change for the plumber. He is bound by the same geometry rules as the carpenter. The precision might be different, but one must cut things to the right length and make sure the angles come together.

I will continue to call the blog SDK writer for now, even though I am not writing for an SDK. I do not think my job has changed that much. Certainly the geometry hasn't changed.

Scenario Cards - Advance organizers

I recently attended a course on Minimalism, taught by Joann Hackos. It was a good and right in line with my thoughts on SDK docs, the normal subject of this blog.

In a doc set, navigation and advance organizers are not always easy to reconcile. To that end, if you have any feedback for my teammate, David Chesnut, we'd be much obliged.

http://blogs.msdn.com/vstsue/archive/2007/06/25/scenario-topics.aspx

We are trying to create some kind of advance organizer that identifies typical scenarios. It's like a "How do I?" topic that is a little more high level.

What do you think? Feedback welcome.

Ham Sandwich

The subject of a ham sandwich came up at our daily meeting and it got me wondering.

No, that's not the end of the blog post.

Seriously, is there any sandwich funnier than a ham sandwich? Turkey sandwich isn't funny. A set up for joke is going to start with something like a man walks into a bar with a ham sandwich. Not a man walks into a bar with a BLT.

Yes, that's off the topic of SDKs. I might add that SDKs are never funny. Ever.

Content synthesizes viewpoints

Documentation or content typically serves two purposes. Documentation provides detailed, code-based information about the software (e.g. reference topics) and it communicates various types of narratives in the form of conceptual content. The latter point is the focus of this post.

When it comes to software, content synthesizes the different ways people view similar things. For example, a customer tends to think of problems. The architects, developers, and testers on the product team tend to think of architecture with a focus on robustness, elegance, and efficiency. Marketing tends to think of features and competitive advantage.

If you are a developer, it's hard to remember sometimes that the user isn't thinking about the thing you are building but rather the problem he is having. Let's get outside of software for an example. Think of housing. A person doesn't want to stand out in the rain, so he decides he needs a dwelling. People have a problem with wet and cold weather. A builder might point out the beauty and symmetry of his building and the efficient use of space. A realtor might point out that in today's market resale is an important point to consider when you buy home. But both those points are peripheral if you are tired of standing in the rain.

This is a drastic and perhaps unrealistic example because housing is an ordinary experience. But let’s see if we can synthesize these disparate viewpoints.

The person (customer) can see the benefit of living in a beautiful, efficient building, and understand how it keeps him warm and dry. The builder (product team) sees the benefits of passive solar heating and the application of green building techniques, irrespective of who lives in the house. And when he evaluates other housing alternatives, the realtor (marketing) sees how certain facets of the building might make it easier to sell it in the future. Content is the pivot point through which communication among the groups is achieved.

Now let’s move from housing to software. Take Quicken and Microsoft Money. Before you used either product, reconciling your checkbook was a different experience. You had an irksome problem. You periodically needed to balance your checkbook so you didn’t bounce checks. Reconciling it with the bank was also a somewhat painful but necessary experience better avoided.

As an old-fashioned checking account user, you were not concerned with the downloadable import format of your on-line statements. And the competitive differences between Quicken and Money were not important to you either.

You needed to have some person or some documentation, i.e. content, synthesize those points and explain to you that on-line banking was an easier, cheaper, faster, less painful way to balance your checkbook.

IT Pro audience

My team is the Team Foundation Server (TFS) team. As a blogger, I don't usually write about the content produced by my team. However, as I consider the documentation produced by my team, a question arises: What is the IT Pro audience and how is it different from other audiences? Technically, my team is in the Developer Tools division (that might not be the official name). I'm part of a group of over 100 content publishers. This includes all the help and documents for language teams, the .NET framework, and so on.

I ran into an colleague, an editor, who switched from Developer Tools to Office. His content team produces documentation for the IT Pro audience. We chatted about how we were both now working with this different audience and how was it different. We agreed that it wasn't that the audience was different so much as the reader/user did different things. It was less qualitative and more functional.

That's how I've settled this question in my mind. SDK readers want different material from IT Pro readers because of what these people do. Carpenters do different things from plumbers. Some activities are similar. They both cut material and fit it together. But writing for the plumber audience would be different than the carpenter audience because one plumbs and the other carpents. That's not right, but I think you see my point. We don't know what either audience does with its personal time (snowboarding or skiing? Letterman or Leno?). And mostly we don't care.

IT pros have different needs than developers based on what tasks they perform. That's the big difference.

How do you measure the production of documentation?

I'm a little tired of discussions about throughput, which is how much documentation work you can do. I understand the importance of this question to a business. Every couple of years, I hear the same stuff. Hours? Days? Topics? Pages? Words? Per day? Per hour? Now a new word is making the rounds: capacity. I think this is a misuse of a good term. Capacity is something of a maximum number not be exceeded. I think a more valuable concept is throughput because it puts the focus on efficiency and streamlining.

When I was a college student, I worked in an injection-molding (thermoplastics) factory. The machines were identified by capacity, meaning how many pounds of force were generated when the mold was closed. The capacity determined the size of the mold you could put in the machine. The size of the mold determined the number of parts per cycle. A bigger mold had more cavities in it for more widgets.

Each machine produced parts at a certain rate. For example, you might be able to produce 10 widgets per mold per cycle, where each cycle lasted 30 seconds. When you do the math, you come up with a measure of throughput.

Half ton machine

• 10 cavity mold * 2 cycles per minute = 20 widgets per minute throughput
• or 1,200 parts per hour

Now this is a very easy model to understand. You can introduce a lot of perturbations to the model. You can increase throughput by reducing cycle time. You can increase throughput by doubling the capacity, i.e. using a bigger machine. Using a 1-ton machine can hold a bigger mold with more widget cavities. This presents you with a set of variables and results that allow you to make decisions.

1. Will the cost of a new and bigger mold be offset by the increase in throughput in a reasonable time?
2. How many more rejected parts do we get if we reduce cycle time? How would that affect overall throughput?

This study is called operations management in business school among other places, and industrial engineers do the analysis.

Basic principles apply to this study, which I'm confident can be applied to the mechanics of building documentation. I don't think documentation throughput is so different that we can't hope to measure it, ever. On the other hand, producing documentation is not so simple either.

Measuring documentation throughput is more complicated than injection molding because the finished products are more variable than simple widgets. I'm not taking anything away from plastics engineering. That's hard stuff, too. It's all toluene this and diisocyanate that. Urethane foam catalysts run amok. Plastics engineers figured out that they make money when the engineers do the hard stuff on their end so that the production of parts is easy.

I would like to see the same rigor applied to understanding the documentation process. That way, we will have a better idea of how it will affect us internally when a perturbation happens, such as a staffing change or a change in authoring tools. While I can see other business uses such as justifying headcount, I think understanding throughput would lead to a better understanding of the internal processes of our team. We can control those more readily and see more tangible results.

Imagine my surprise

I have to say thanks for reading this blog. I'm a bit clueless on the 'drive readership' part of writing a blog. Mostly, I hope that people read stuff and not laugh, except when I'm trying to be funny.

Imagine my surprise when I discovered there are actual statistics maintained about the blog viewing. Even more surprising, hundreds of people have read my blog. I have approximately a big family so that could explain it. Or robots.

Either way, thank you Dad and your robot too.

Snark and me

I really like when someone gives me feedback on my blog. This is an odd feeling for me because I have a tendency to minimize things like praise. It's my ambivalence issue; I own it.

Part of my personality is a little like Stuart Smalley, who I hope I can reference with out paying a royalty. Stuart Smalley is a character of Al Franken's creation who wrote a book called I'm Good Enough, I'm Smart Enough, and Doggone It, People Like Me!: Daily Affirmations With Stuart Smalley.

On the other hand, my personality tends toward snarky. I'm a sarcastic person who grew up in the North East of the good ole US of A. While sarcasm comes easy to me and can be entertaining to some people, sarcasm has also caused the occasional mis-understanding. I have a tendency to think everyone can handle this type of sharp dialog and wants to engage in the same kind of banter that I like.

When someone praises my blog (feels good) but they praise the snark within the blog, I'm not quite sure how to react. I think they think the snark is funny or, at least, more honest. It is entertaining, I hope. It does reflect a bit more of my inner dialog. But I feel some measure of caution is needed with snark. Overly snarky is divisive, off-putting.

I don't have a PollyAnna attitude of "can't we all get along" but neither do I want to unnecessarily offend someone. Dialog is good. Sometimes it isn't pretty, but it's easy to shut down somebody (stopping the dialog) if you get all snarky.

Aiming for some balance here, is all.