It's not me, it's you

I'm speaking at WritersUA conference in Seattle (March 29-April 1). One of my topics is "Managing UA Projects with Spreadsheets" in which I explain why I broke off my long-time relationship with MS Project to go with Excel as my tool of choice for managing user assistance projects. It includes a full tutorial that will put attendees in an exclusive club: folks who can do pivot tables in Excel. Hope to see some of you there!

It's not me, it's you

Going Global and oh so Web 2.0

I added a translation widget to my blog. Scroll down the navigation pane on the left to find it. View this blog page in the language of your choice.

I've started trying to pick up my Arabic again (I was a translator for the Army Security Agency about a bazillion years ago) and that has gotten me interested in online translation tools. This particular widget has a nice mouse-over feature that lets you see the original text. Try it.

Cognitive Tools

Tom Johnson has a post on one of my favorite topics, Tools. It's not that I'm a tool fanatic, it's just that I'm fascinated by how they interact with our creativity to shape the products we make. I've long been an advocate that teaching technical communication without teaching tools is like teaching art students about painting without talking about brushes.

An aspect of tool use and evaluation that sometimes gets overlooked in tool discussions is to what degree a tool helps the user think better. The academic phrase for tools that do this is cognitive tools. Cognitive tools are closely related to performance support tools, but I draw the following distinctions:

• A performance support tool manages workflow and pushes data to the user based on the programmed expertise about the job domain the tool is programmed to support. A troubleshooting script is a performance support tool. I can use it to solve my problem but not get any smarter about troubleshooting.
• A cognitive tool helps me think about the problem space or job domain.

Whereas a performance support tool typically answers questions I ask, a cognitive tool helps me come up with questions I would have never thought to ask. Performance support tools help me do; cognitive tools help me understand.

I like tools that have a bit of both. For example, a word processor is typically a performance support tool. It lets me enter and edit text efficiently. But I often switch into Outline mode partway into writing a document and look at just my headings. All of a sudden I can see structural flaws or problems with flow that I had not noticed while immersed in the content. I can then shift topics around until I see a structure that feels right. It is the tool's ability to tap into my intuitive processes that gives it a value above its ability to enter, copy, paste, and spell-check.

Now that I am sensitive to this intuition support aspect, I am seeing all kinds of examples. Watch the video embedded in a blog about the future of the Web to see how faceted metadata searches can tap into an intuitive need to understand more but when you can't articulate the question. Warning: the initial example assumes that the reader has a well articulated question, but watch later examples as the tool helps a vision of possible relationships emerge.

Pivot tables in Excel (or pilot data tables in Symphony) have the same ability to let me kind of "poke around" in the data until I stumble on interesting relationships I had not thought to inquire about.

Ours is a very rational culture that holds a strong belief that good documents start with a clear outline, good training starts with crisp objectives, and good design starts with exhaustive requirements.

I think real projects start with some unstructured poking around that eventually converges on a clear vision of what needs to be done. Furthermore, a goodly portion of that poking around has to be done in production mode (including production tools).

So I would add a criterion to evaluating tools: Do they support cognitive activities such as analysis and relationship modeling; specifically, can they support "what if" experiments that are easily reversed if they go nowhere useful and on the other hand can be easily implemented into the production model if they prove useful.

The Information Model

Continuing our discussion of using Excel rather than Word or Project to manage an information project.

A simple spreadsheet that I get a lot of use out of is one I call the Information Model. I use it first to plan my information content, then to estimate the development time for each topic (or group of topics) track who is responsible for each, the due date, and its status. It is a simple, flat table in Excel that has columns labeled Topics, Info Developer, Status, Estimate, Due Date, and Comments (for starters).

If you are revising an existing document, the topics in the spreadsheet can be taken directly from the existing document. If the application you are documenting has a UI already, you can list the UI pages themselves as the topics. If you are using use cases, you can add a column to help organize your topics by the use cases or scenario names that describe the user tasks you intend to support.

You can now use the same spreadsheet to assign different topics to different information developers.

You can also use the spreadsheet to size the project. For example, in one project the general scope of a screen could be described by the number of tabs it had. So I created a column called tabs and we inventoried how many tabs were on each screen. We then estimated that each tab would take a half-day to document, so we wrote a simple formula in Excel to estimate the days each topic would take by multiplying the number of tabs by .5. We then summed that column to see the total project estimate.

• Tip: Put the estimation variable (in this case we started with .5) in its own cell and point to it in the estimation formulas. For example, if the estimation variable was in cell H3, and the number of tabs for a particular topic was in B5, the estimation formula for that topic would be "=$H$3*B5" Note: The $ makes that an absolute address, so if you copy that formula for all the topics, B5 will automatically change to the appropriate cell that contains that topic's number of tabs (e.g., C5, D5, E5, etc.), but the estimation variable will always come from H3. This way you can play some easy "what if" scenarios by changing the estimation variable in H3 and instantly seeing the impact it has on the project time.

Once the topics have been sized and assigned to information developers, you can ask each info developer to schedule their assigned topics. For example, if an info developer thinks she can devote an effective 3 days a week to the project, then she could group topics into weekly chunks by assigning the same weekly due date to 3 days' worth of topics. Or if a topic would take 6 days, she could make sure she allocated two weeks to get it done.

• Tip: Have info developers make all topics due on Fridays. That way the project manager or department manager can filter by a given date to see everything due that week.

And that last tip brings up a really useful feature of Excel, the ability to apply filters. Once you have your table built, do the following:

1. Highlight the heading row for the data columns.
2. Click Data > Filter > Autofilter on the menu.

You now get drop lists at the top of each column that let you filter and sort the table by the data in that column. This lets you do things like see only the topics that Mike is working on, or only the topics that are due this Friday. You can apply multiple filters, e.g., see Mike's topics that are due this Friday or see Mike's topics where status is blank.

Of course this approach needs to be modified for what make sense in your world, e.g., I like weekly scheduling units, you might prefer monthly. But the point is, if you put your plan in a spreadsheet instead of a document, you get a more powerful database and calculator tool to help you plan and track the project.

Plan vs. Planning

[Duh! after almost two years on Blogger I figured out that there is a "title" block that is not turned on by default. I looked for it when I started transferring my rss reads from NewsGator to Google Reader. All of my blogs said "No title" and everybody else's had titles. It's the cyber equivalent to spinach in the teeth-it leaves you wondering why no one tells you :-0 ]

Documentation Plans: One out of Three Rs

We have a couple of overlapping projects going on at work these days. One is to establish ourselves at Level 3 on the Information Process Maturity Model. Another is to be more compliant with IBM's Information Development Standards. The upshot of this is that I am reflecting on the planning process a lot these days, since both of these efforts deal with planning.

My second career (after being an electronics technician--so long ago I know how vacuum tube circuits work) was in Manufacturing Management, so I have a natural fondness for project planning and tracking which I carried forth into a later career of documentation management. In my current career as Information Architect I find my need for project planning and tracking tools are still welded to my genetic structure. But I have noticed my tool of choice has changed over the years and that my reverence for "the plan" has diminished a bit. But not my respect for "planning," which is what this blog is about.

In short, a lot of mature departments and those striving to be mature place a lot of importance on a written documentation plan, often produced in MS Word and sometimes accompanied by a formal project plan done in MS Project. If I had a nickel for every such plan I've done--well, I'd have about $1.35, which rhetorically doesn't sound too impressive after having done the math, but you get the idea; I've done it a lot.

I think documentation plans have some serious flaws:

• We do them when we are the stupidest about what the project is about and whom it is for.
• Although we write them (one R), I'm not sure anyone reads them (second R).
• Lastly, they lack detail and the underlying engine to do the estimation math (the third R 'rithmatic).

I think project plans done in a project planning tool also have some serious limitations:

• They treat the project as if it is progressive (it keeps moving forward in discrete chunks) and linear (it moves in a straight line). In reality a project is expansive (we learn more about the product, the users, and our production tool sets the further into it we get into the project) and recursive (this expanded knowledge we get by the time we're on chapter three makes us need to rewrite chapter one).
• The critical piece of information we are all after, task duration, is an input and not the result of anything the tool helps us with.
• Whereas just about everybody has Word, Project is not as ubiquitous and distributing the project plan is not as easy as distributing a Word document.

My Tool of Choice

I find I'm getting much better results by using Excel as my planning and tracking tool.

• I spend more time thinking and noodling and less time on writing a document. The subtle difference is that I have shifted my emphasis from "making a plan" (where the plan is an artifact to be distributed and checked off) to "planning."
• Excel is great for making and manipulating lists. Once I have identified topics, assigned writers, categorized topics, set dates, whatever, I can filter and sort by any of those classifications.
• Once the list of topics is created in Excel, I can use its calculation capabilities to help me estimate the project.
• Everybody has Excel and the plan, schedule, and tracking file for a project (a single workbook with multiple worksheets) can be placed on a shared drive and be viewed and updated by anyone on the project.

The problem is that Excel is not usually considered a technical communicator's tool and so we do not get exposed to it in school or at the conferences. I'd like to see that change, since it is uniquely capable (by "it" I really mean a spreadsheet tool) of letting a project plan mature from broad, static statements to detailed inventories of information topics to be developed and then let you calculate estimates for those topics and create realistic schedules that can be monitored at a weekly granularity.

For the next few blogs, I will discuss in more detail how a spreadsheet can be used to plan and monitor information development projects. Even if you do not throw away your conventional documents about documents approach to planning, maybe you will find it worthwhile to stick a couple of more Rs into the process.