mike's web log

Tech Review Tips and Strategies (Part 2)

Thu, 26 Aug 2010 17:13:08 GMT

This is a continuation of the previous post about tech review. (Part 1).

Ok, we've seen some tips. What's the best way to conduct a tech review? There are many; the list below represents ways I have personally seen tried. Each approach has pluses and minuses. None are perfect, but if one isn’t working for you, try another.

Send out hardcopy

Advantages

People can review practically anywhere.
Easy to get you incremental reviews – e.g. "Here’s the first 20 pages."

Disadvantages

Lots of people prefer working in soft copy.
Need a way to show overall context of the docs you’re sending out for review.
Handwriting can be hard to read, and people use idiosyncratic editing marks.
Reviewers can't see each other's comments.
Comments have to be transcribed.
Can use a whole lotta paper.
Potentially hard to enforce your schedule.

Send out softcopy (e.g. Word files) individually to each reviewer

Advantages

Reviewers can do softcopy edits – for example, use Word’s revision marks and comments.

Disadvantages

Reviewers can't see each other's comments.
Need a way to show overall context of the docs you’re sending out for review.
You must individually collate comments.
Your doc format has to lend itself to this (i.e., might not work if you use proprietary authoring tools that your reviewers don’t have access to).
Potentially hard to enforce your schedule.

Post a complete read-only doc set in a central location and specify which docs to review. [more]

Tech review tips and strategies (Part 1)

Fri, 20 Aug 2010 21:57:12 GMT

Not long ago, I posted some notes about what not to expect from a technical review of your document. One premise is that tech reviews are inherently limited in what they can provide you. When I was pinging people for ideas on that post, more than one person said it would be equally (or more) useful to post something about how to nonetheless get the best technical review that you can. This is a topic of perennial interest; I believe that there's been a session on how to get good tech reviews at every tech-writing conference I've been to.

Herewith, then, some ideas. I will actually start with general tips. Next time, some strategies.

Tips

Spell out what you want from the reviewer. Don't just throw it at them and hope for the best. Leave questions about specific things you want to get answered or draw their attention to. Colleague Brian left the following suggestions as a comment on the previous post:
I have a little boilerplate message telling them I want to know two things: (1) Is what's there correct? Run the code, try the steps, etc. (2) Is anything not there that should be?
Prioritize. You will have more to review than they'll have time for; not everything can be reviewed. Pick out the material that's most critical. Include the pri-2 stuff if you want, but make sure your priorities are clear to the reviewers. (See also next point.)

Don't overwhelm. Choose a reasonable number of topics for review, not the entirety of a 1000-page book or doc set.

Be aware of the reviewers' schedule [more]

Pity the intermediate user

Thu, 12 Aug 2010 11:57:42 GMT

Gordon Meyer has, as usual, an interesting snack for thought:

Here's a fun exercise to try: Take a manual for a product that you know well and markup each section with who you think the writer is addressing--beginners, intermediate, or advanced users. Then calculate the percentage of the book dedicated to each type of audience. If there is a gap in the middle, as there often is, ask yourself if the documentation is truly serving the product's best interests. Expert information in a beginner's manual befuddles new users. Manuals that too dumbed down infuriate the experts. Those who somehow manage to graduate from being newbies? Well, I guess they'll figure it out.

This is one of those ideas that rings true the moment you hear it. In my own world, we put a lot of effort into ramp-up documentation -- start-up tutorials and overviews. However, our product, and to some extent the documention, has had the reputation for holding your hand tightly when you're a total newbie, but then dropping you off a cliff when it's time to move beyond the beginner stuff. And, of course, as Meyer suggests, we do create documentation that's strictly for experienced users, where we assume that the reader has fairly deep background on the topic in question. I would like to think that we provide a reasonable bridge from beginner to intermediate user, but I'm sure there are many users who would beg to differ.

[more]

Handling version changes in documentation

Tue, 10 Aug 2010 18:12:27 GMT

Just wondering what sorts of examples people might have of documentation sets that cover multiple versions of the same product. In our doc set in MSDN, we basically republish each complete doc set, but updated for the new version with corrections and new features:

The advantage is you can go right to your version and be assured that what you're reading applies to you. The disadvantage is that the versions pile up (4 versions and counting), with a lot of overlap, which is inefficient in various dimensions.

Are you familiar with a doc set that handles versioning differently than this? (Conceptual or API reference or both.) If so, leave a comment with a link.

Thanks!

What to expect from technical review

Wed, 04 Aug 2010 21:38:42 GMT

I had an incident recently where I was having a sort of disagreement with a writer about some content in a document. The writer's trump card, so to speak, was to note that "It went through tech review!" As far as the writer was concerned, it had been reviewed, and the reviewer (or reviewers, I forget if there was more than one) had not indicated the change I was after, and that was that.

This gave me pause. We try to get a technical review of anything substantial we write, and we put a lot of stock in those reviews. Yet I still felt that whatever change I was arguing for was valid. So that got me to thinking about tech reviews and where they fit into the overall scheme of things when it comes to assessing the done-ness of a document. Conclusion: reviews are good (indeed, essential), but they're not the last word.

Why is that, tho? Well, here are some of the reasons I came up with (with help from the folks on my team) as to why a tech review might not be giving you the entire story:

TR is often done in a big hurry. It tends to come at a bad time for our reviewers, who have their own pressing deadlines to attend to. Anecdote: For our most recent release, our primary reviewer read something like 10 of our chapters all in one day (Father's Day, in fact). How carefully do you think he considered everything he was reading?
In our division, TR is mostly about code. One thing that interests most of our reviewers is code, and they'll usually read that. Descriptions? Background? Step-by-step procedures? Maybe. Even so, reviewers often do not run code or follow steps to see if they work. One of my writers is quite adamant on this point: "Assume they haven't run your code. The burden of testing code is on you."
[more]

Technical writer interviews: Part 2

Thu, 01 Jul 2010 17:52:34 GMT
Last time I talked a little about the interviewing process and investigating the technical side of technical writing in our group. If you don't pass a technical screen, we're unlikely to pursue the interview. But assuming you do get over whatever bar is set, comes now the writing side.

A diversion. As I will touch on later, there's a difference between a person who can write and a person whose job is writing. A programmer who writes the occasional blog entry is not (yet) a technical writer, who in contrast spends week after week documenting not just the interesting and cool things that are fun to write about, but also the seemingly endless APIs, the unsexy readme files, the installation instructions, and all the other stuff that users need, and who do this on relentless schedules. (As people sometimes say, "that's why they call it work").

Ok, writing. How do you assess writing skills, and specifically technical writing? If anyone's developed a foolproof way, I haven't heard of it.

[more]

Technical writer interviews: Part 1

Tue, 29 Jun 2010 23:21:39 GMT
Someone I know was prepping to interview for tech writer job and asked whether I had any thoughts on questions that might be asked. I don't know too much about how it works in the wide world, but I did give a thought to how we (well, I) think about the interview process.
Before we get any further, I need to say this very clearly: what you read here does not necessarily reflect company policy, or our team's philosophy, or any specific or actual interview questions. What you're getting here are my personal thoughts about the interview process for technical writers. Ok, with that out of the way ...
If you interview in our group, you're looking for a "programmer/writer" position, meaning that you're a writer and you can program. So the interview process has to address both the technical and the writing.

There’s some difference in how this is handled for full-time positions vs. contracting positions. For contractors, the idea is that we’re looking for someone with a specific set of skills to solve a short-term problem. As such, the interview process focuses on drilling down into those skills and what the candidate can do to help with that particular problem. For a full-time position, the idea is that you’re hiring not just for now, but for 10 years from now. FTEs are an investment, so you’re looking as much for aptitude and what the company calls "core competencies" as you are for those specific skills. The FTE interview cycle is necessarily more elaborate and wider in scope.

[more]

Why not have developers write the docs?

Sat, 29 May 2010 13:05:55 GMT
Occasionally (or frequently, depending on the exact context in which you work), the idea will be floated that the way to do API documentation is for the actual developers to include comments in the code, and then to extract these. A number of tools exist to faciliate this, including Javadoc, Doc-o-matic, GhostDoc, and Sandcastle. (Wikipedia has a long list of such tools.)

The idea is appealing in a number of ways, among them:
The developer developed the code, so they understand it best.
When an API changes, it's easier to change comments in source code than to track down and update some document somewhere.
That's one less technical writer you need to hire.
In my experience, tho, there's little guarantee that you'll end up with decent documentation. Here's a list of reasons why:
Most developers would rather code then write. This is all the more true, I think, when the writing consists of revising existing docs (comments) for an update.

Is it cost-effective to have developers writing documentation at coder rates? Maybe, maybe not.

Many developers are not strong writers, mechanically speaking -- not just spelling and grammar, but being able to articulate what it is they need to say.[1]

[more]

Show and talk: documenting code

Tue, 18 May 2010 23:25:24 GMT
What's the best way to document a procedure that consists of code? For example, maybe you want to show people how to use code populate a listbox from a database. (And I mean code; we'll assume that somewhere else you've already documented how you can do this with little! or! no! code! Ok.)

Well, you're going to have to show the code, duh. Do you ...
... show it first and then explain it? (Show, then talk.) Example (tho not of this task).

... explain the algorithms and then show the code? (Talk, then show.) Example.

... walk through the code line by line, explaining as you go? (Talk, show, talk, show, talk, show, ...) Example.

... forget the yack, just show the code. (No talk, just show.) Example.
Each has some advantages and disadvantages:

If you list the code first, readers can have a glance and then decide whether they even need to read your explanation. Downsides: readers can go into code shock. It can be hard in the explanation to reference specific lines (without repeating them). Also, really large samples don't lend themselves to the aforementioned glance.

If you explain first, you can provide an overview, plus any setup that the reader might need. ("You must create an instance of the foo class and call its bar [more]

Uh ... ok, duly warned

Mon, 17 May 2010 09:09:43 GMT
I saw the following stuck on the side of a bathtub in a hotel room:

We're used to seeing all manner of warnings and cautions, of course, both negative (Do not ...) and positive (You must ...). But I sure can't figure out why I'm being told this, or exactly I'm supposed to do in order to "exercise normal precaution."

Why are readers so annoyingly dumb?

Tue, 11 May 2010 19:13:55 GMT
Jeff Atwood once made the observation that[1] ...
Of course, the real problem with software development is the users. It's unbelievable. They've caused problems with every program I've ever written.
I can relate, as can most (all?) technical writers. Sometimes it seems as if readers willfully misinterpret your text to be as far removed from what you actually intended as possible. It's ... exasperating.

You write:

This topic describes how to connect to the sample database with an .mdf file.

It's perfectly clear to you, of course, that the database has an .mdf file and that you want to connect to such an .mdf-file-implemented database. But the obtuse reader will look at that and ask "How on earth do I use an .mdf file to connect to a database?"

Or you write:

The template includes common files that are used in many Web applications.

Obviously when you wrote common you meant typical, but yer dumb reader probably will ask "Do you mean the files are shared between applications?"

If they were right there, they could ask and you could clarify. Alas, all they have is your text and the aforementioned tendency to misread you.

Indeed, I do this myself. Here's a set of instructions on the back of a bottle of Fogtech, a product I have extreme need of while motorcycling around in the Seattle winter[2]:
Apply Fogtech® to a completely dry lens.
[more]

Writing for Games

Tue, 06 Apr 2010 09:08:35 GMT
My friend John is interviewed for the Microsoft JobsBlog on how it is that a technical writer works in the Games division:
How did your career start off at Microsoft Game Studios?
I was working as a technical writer for Microsoft on error messages for Office 95 and telephony projects and that sort of thing. But, like a lot of technical writers, I had a secret life. When I wasn’t at work, I was busy as a screenwriter.

I started working in games in 1996 when a former copy editor of mine from Office asked me to create an online help system for Mind Aerobics, a new puzzle game by Alexey Pajitnov - who invented Tetris. In many ways, my first game writing job was still technical writing.
A while back, I heard a presentation that John did about how the role of writer works a little differently in games than it does in the kind of writing we do. To me this is still one of the most amusing summaries of why reading technical documentation can be less than fascinating:
In technical writing, we want to get to order as quickly as possible.

In story telling, we play with the state of disorder and give out pieces of order a little at a time, strategically, so we can maintain dramatic tension and drive interest forward.

So a technical writing approach to Star Wars would have a big bolded notice on the first page that said, Important! Darth Vader is Luke’s dad!

Where do tech writers get their information?

Sun, 04 Apr 2010 14:27:38 GMT
Someone recently sent me a question that boiled down to "When you document a new product, where do you guys get your information?" When you're part of the documentation team that's working on a new, not-yet-released product, you can't just load up the product and start poking around, because for some significant portion of your scheduled time, there's no product to be poking around in. And by the time you get some early product builds that are stable enough to play around with, you're rushing toward deadline.

So it's a fair question. I consulted with our folks, and this is the answer we came up with. First of all, the process varies a bit depending on the team, of course. Our general process is that product features are developed by feature crews that have team members from all affected disciplines (program management, development, test, and documentation, hopefully including localization). Feature crews develop an initial specification that goes through an approval/sign-off process. The product is then built from the spec, and we're done!

Haha. In reality, of course, things are often more fluid -- before, during, and after the development phase. Feature-crew specs are in general a starting point for our information, but like all specs, they vary in how much information we can glean from them, and as we all know all too well, the spec is often not maintained after coding begins in earnest. If that's the case, writers have to be a bit more resourceful in getting information. Sources of information for us therefore include:
[more]

Linking: quality, not quantity

Wed, 03 Feb 2010 00:32:45 GMT
More on linking. (Earlier post) Compare these snippets in which the reader is invited to go elsewhere for more information[1]:

Version 1
For more information, see How to: Configure Specific Directories Using Location Settings and the System.Web.Configuration namespace.
Version 2
For more information, see the following:

Tasks
How to: Configure Specific Directories Using Location Settings
How to: Lock ASP.NET Configuration Settings
Reference
system.web Element (ASP.NET Settings Schema)
configuration Element (General Settings Schema)
System.Configuration
System.Web.Configuration
HttpRuntimeSection
HttpRuntime
Concepts
Caching ASP.NET Pages
ASP.NET Configuration File Hierarchy and Inheritance
Securing ASP.NET Configuration
ASP.NET Configuration Scenarios
Other Resources
[more]

Logical AND -- in English, not programming

Sat, 12 Dec 2009 12:24:37 GMT
In my work, we deal with a lot of uses of the term and that are defined rigorously, speaking in the logical sense. Which is to say, in the programming sense. For example:

If firstTime = True And listCount > 0 Then ... End If

The AND expression here is clear: both conditions must apply in order for the result of the If test to resolve as true.

So that's programming (and formal logic). English syntax is a bit looser. What do you make of a sentence like this?
This property returns true when the HiddenInput attribute is true and the HiddenInputAttribute.DisplayValue property is set to false.
The scope of the word and here is not exactly clear. Does it mean (condensing here):

The property returns true when HiddenInput is true, and it also returns true when DisplayValue is true.

Which would basically make the grammatical and (illogically?) into a logical OR. Or does it mean ...

The property is set to true when both HiddenInput is true and DisplayValue is true.

Meaning that both conditions must be true.

What do you think?

"Linux Bug #1: Documentation"

Thu, 03 Dec 2009 21:52:49 GMT
I ran across an interesting article ("Is Bad Documentation Derailing Linux?") that floats the thesis that the lack of good documentation is hurting Linux acceptance. I don't use Linux (perhaps for obvious reasons?), so I don't have any first-hand thots on the state of docs for that product.

However, I do understand that good docs are an investment and that complete docs are practically impossible, even if you're paying a fleet of tech writers. As I've noted before, we have various reasons, some of them involuntary, to spend considerable effort on providing at least some docs for every last flippin' member in the .NET Framework. The count of a list of these members goes well into 6 figures.

At various times, folks I've worked with have done analyses of some open-source docs. There is much very fine work out there, no question. A comment that comes up, tho, is that the docs for OSS tend to cover cherry-picked topics -- there is excellent documentation for interesting features, but the quantity and quality tends to fall off as the scenarios get less mainstream. This is hardly surprising -- who wants to contribute to a community by slaving away at documentation that's obscure?

[more]

An opportunity to avoid

Sun, 22 Nov 2009 07:42:41 GMT
You have to wonder why this was phrased the way it was:
SOAP is supported in many different environments but is considerably more complicated than XML-RPC and presents more opportunity for interop problems.
I had to think for a second about why this bothered me; it's the word opportunity. The term's connotation (to me, to Random House, and, I think, a lot of people) is essentially favorable: Don't miss this opportunity! But the "opportunity" to introduce problems is not one I want to take advantage of, eh?

Why not just [...] can present more interop problems -- ?

So, let's repeat our mantra, shall we? What these people need is an editor.

More dubious copy

Sun, 15 Nov 2009 16:19:53 GMT
This isn't really dubious guidance, strictly speaking. More like dubious marketing, or maybe more succinctly, WTF marketing. Check it out:

As in:
Wouldn't one expect a product to, like, work?
Is there a general expectation that (e.g.) knife sharpeners don't work?
When I am shopping for a knife sharpener, is the deciding factor that the manufacturer claims that their version actually is functional?
You can get a service mark (sm) on the phrase "This really works!" Really?
But, of course, you'll note that this is a package that belongs to me. So perhaps I should be asking myself these questions, eh?

More dubious guidance: 1, 2, 3, 4, 5.

That renumbering problem with Word lists

Tue, 03 Nov 2009 08:46:07 GMT
When I teach Word styles, I make the case that although the features in Word for creating lists are pretty powerful, there's an inherent limit in list styles. There's a useful chart that I found somewhere[1] that shows the kinds of styles that you can create and what attributes you can set for each type of style:

You can see that in the List column, there's no checkmark for paragraph formatting. This is evident if you create a list (as opposed to paragraph) style:

(Multi-level list styles do let you specify a different indentation for each list level, at least.)

If you use the automatic list features of Word (), or if you create a multi-level list style, you end up using a style called List Paragraph. This is technically a paragraph style, and for List Paragraph you can modify the style definition, but frustratingly, any changes you make to paragraph styling, such as indentation or spacing, appear to be ignored.

For quick-and-dirty list formatting (which probably covers most people for most situations), this isn't really a problem. At work, however, we often need to specify interlineal spacing or other paragraph-y formatting, or we need to be able to set different characteristics for different indentation levels.

What we do, and something I tell students they can do if they need this level of control, is not to create a multi-level list style. Instead, go with the approach that olde tyme Word users know -- create a paragraph [more]

Documentation survey!

Fri, 30 Oct 2009 14:35:27 GMT
Do you use our documentation? (Golly, hope so. :-) ) Give us some feedback -- take the survey that's posted here:

https://www.surveymonkey.com/s.aspx?sm=qQnlYIN2D5gQH7UhLrQyuA_3d_3d

This asks some basic information, like where you get your technical information and how you go about finding it, as well as how best to get your feedback, what type of development you do, etc.

I can assure you that we look at this stuff intently, we really do. I encourage you to go through the survey. It's only 11 questions, and it will help us out.

Thanks!

New location (and look) for ASP.NET documentation

Mon, 19 Oct 2009 10:41:18 GMT
ASP.NET documentation actually has a couple of homes. There's the grab-bag of articles, tutorials, and videos about ASP.NET that's posted on the http://asp.net site. And the official documentation -- the stuff I work on -- lives on MSDN, the gigantic library of Microsoft information.

We released Beta 2 of the .NET Framework 4 and Visual Studio 2010 today. As part of the docs push, we managed a change that we've actually been wanting to make for a long time. Since approximately forever, our stuff has been part of the overall Visual Studio documentation, and it's taken some digging to find it:

Whereas all this time we've had this other node in MSDN that seemed like it would make a good home for our docs. And as of today, that's where you'll find our stuff:

The new organization reflects a couple of things. One, obviously, is that if you're scanning the MSDN table of contents (TOC) looking for ASP.NET stuff, a pretty likely place to look is in a node that's about Web development. We wanted to reduce the clicking required to get to the doc, of course. Another change is that because the docs are not tied specifically to versions of Visual Studio, you can see that we can keep ASP.NET 4 and ASP.NET 3.5 documentation close to each other in the TOC.[1]

[more]

Am I just too stupid to understand this, or what?

Mon, 05 Oct 2009 17:15:19 GMT
As I've mentioned before, readers in general are apt to give text the benefit of the doubt.[1] They'll take it at face value and they will assume that what they read is true. And they'll assume that they are reading about the culmination of a process that involved a lot of thinking and designing.

For the most part, this is true. When you are reading instructions for something, you're dealing with a product that was created with some forethought, that the process you're decyphering was designed and agreed on, and that the steps you're reading are the true, correct, and best way to accomplish your goal.

Sometimes, however, you run across something that is just hard to figure out. You read a paragraph and you go "Huh?", and you look through the steps and you just cannot seem to understand what's going on. A typical reader's first reaction, I will posit, is that it's their fault that they're not getting it. They'll read again, and if that doesn't work, they'll try something else. (These days, they might go look something up on the Web to see if they can get a different explanation.) If the information still seems hard to follow, though, they might find themselves wondering, even if fleetingly, if maybe they're just a bit slow.

Dunno, maybe they are. (haha, joke) But I can tell you a little bit from the other side of that text they're struggling with, and I can let you in on a little secret about tech writing: sometimes -- not always, but sometimes -- when something is hard to describe, seems convoluted to document, has steps that are difficult to follow ... well, sometimes it's because the process being described is kinda stupid. Stated more succinctly: If it's difficult to describe, maybe it's designed poorly.
[more]

Top lies heard by technical writers

Fri, 18 Sep 2009 09:18:10 GMT
Ha. I was going through o-o-old emails and ran across this. (No idea who first compiled it.) The list was actually quite a bit longer and included lots of allusions to printed docs, which tells you how old it is.

Funny, anyway. If you're a technical writer, tell me you haven't heard at least a few of these uttered.[1]

I'll take it along and read it on the plane.

I'll read it over the weekend.

I'll return this to you with my comments by the end of the week.

Code will be frozen 12 weeks before your document is due.

There's plenty of time in the schedule for these changes.

I don't really have an opinion on how you labeled those controls.

One space, two spaces. It doesn't matter to me.

We're ordering you a faster computer and a 21" monitor tomorrow.

We've never had any complaints about our documentation.

You'll have the full support of upper management.

The style guide covers every possible situation.

Designers and developers will ask for your opinion on GUI design, layout, and functionality.

You should have a fully-functional product in your hands in plenty of time to complete your document.

Your document probably will not need to be translated.

The product's so intuitive, it practically writes the manual itself.

There's just one major feature change and some bug fixes.

This is the latest copy of the software.

All the information you need is in the specs.

The procedure should only take a page, two at the most.

Communication is our priority.

The software is frozen.

You will have full, unrestricted access to the development team's time.

No rush.

[1] [more]

The which that restricts (The that which restricts)

Thu, 17 Sep 2009 09:38:43 GMT
It is a non-truth all too often acknowledged, that a clause in possession of a restrictive relationship must be in want of a that. Any conservative-leaning guide to grammar will insist that you introduce "restrictive" clauses with that, and "non-restrictive" ones with which. Our corporate style guide is no exception; here's our guidance on the matter:

Correct
You will need to supply information about applications that you want to run with Windows.

Incorrect
You will need to supply information about applications which you want to run with Windows.

Correct
Your package contains the subsidiary information card, which you can use to obtain device drivers or local technical support.

No professional linguist takes this seriously. There's no evidence from actual English usage, contemporary or historical, that which is not suitable for introducing restrictive clauses. (You can find recent talk about this on the Langauge Log here.)

Why am I blathering on this? Because I have yet again found something amusing on Facebook. This time it's a description of one of the innumerable games that you can play via Facebook. (As if FB just by itself were not already a yawning time suck.) This particular game appears to be a typing type of game, which is described thusly:
Typing maniac is a game which measures the typing skills and the ability to think fast that features multiple power ups!
There is editorial gold here, including a capitalization error (Typing Maniac). But more to the point, it's a rare instance where that and which [more]

Standard by mistake

Tue, 15 Sep 2009 16:18:11 GMT
I'm pleased to be able to note that I've had a piece published on the Thinkmap Visual Thesaurus site. The site is restricted to subscribers, so although I can link to it, you won't be able to read it unless you are already signed up. (And what better reason, really, than to read this article? :-) )

The theme is mispellings that come to be accepted, like HTTP_REFERER and SHStripMneumonic, because by the time someone notes that there's an error, the name is already established.

It was good fun -- I'm hoping to be able to submit some more in the future. Naturally, I'll let you know.