Update or rewrite: how do you decide?

This is a common scenario for technical writers: there is existing content, let’s say for V1 of a product, and the same content needs to be provided for V2. Do you limit your work to making changes to the existing content for technical accuracy with V2? Or do you start with a blank slate and…

0

Changes to OpsMgr docs (System Center 2012) in Dec 2011

If you follow us on Twitter (@opsmandoc), you’ll be hearing about updated documentation for the Release Candidate being available later this week. Both TechNet and the downloadable docs will be refreshed. The following are the significant changes you can expect, in addition to added links and minor language fixes: The Authoring Guide adds a new…

0

Operations Manager: what do you need to know to use it?

This is actually an open question to you all. 🙂 It’s common for us to say our audience is the IT pro. But “IT pro” is a lazy shortcut to refer to a wide variety of people and positions. Does every IT pro know how to configure and manage permissions for SQL Server databases? Not…

0

Need volunteers: Operations Manager documentation survey

Do you use Operations Manager? Would you be willing to complete a short email survey about operations documentation? If so, please send email to momdocs@microsoft.com. More details: The survey will be sent out approximately 21 March. We will use your responses to help us make decisions about organization and terminology so that the Operations Guide for…

2

Which user role(s) can perform this task?

The content team is busily ramping up on doc plans for the next version of Operations Manager. (And I’ll be very careful not to reveal anything about product changes, features, etc.) I’ll be owning the operations content, so I’m working on new outlines and identifying current gaps. As I was going through the current content,…

0

Writing good technical documentation, part 3

(Part 2) (Part 1) Nathan Bransford, a literary agent, blogged about his difficulty in getting writers to paste their original query into their partial manuscript. Here are the instructions he sends them: “Thank you for your recent note. Would you mind sending me the first 30 pages in a Word attachment? Please paste your below…

0

Writing good technical documentation, part 2

(Part 1) Joel Spolsky has an excellent post on the role of the program manager. I work with program managers, so I read through it comparing his descriptions with the PMs I’ve known. Then I got to the part on functional specifications and my interest level jumped a few notches. Because the spec is –…

0

Writing good technical documentation, part 1

A recent comment by “BPM software” suggested that I write about best practices for writing technical documentation. I thought about it for awhile and decided I couldn’t really do it justice in one post – hence, “part 1”. I’ll begin by plagiarizing myself. What I said about management packs is just as true in this…

1

How not to write a user manual

I have to disagree with Tony Soper’s admiration for the Pong user instructions: “Insert quarter Ball will automatically serve Avoid missing ball for high score” Tony and I worked together on the same team, so he’s used to my contrariness. 🙂 I don’t object to calling Pong’s instructions “succinct”, but I just don’t think they’re…

3

Web vs. print challenges

If you took a look at the DPM 2007 Operations Guide during the beta, you might have noticed that the server chapters have a similar organization: general maintenance management data recovery And within those sections are parallel topics, such as: renaming the server applying OS updates using Windows maintenance tools A few times I’ve questioned…

0

It’s worth your during

I know, you’re tired of hearing about difficulties translating the american-english language. Still, when I encounter such an amusing example, I just have to share… They didn’t care about my schedule, offering only general remarks about making it “worth my during.” I think they meant “while.” From Alison Bowman’s The Copywriter, via the Slush God.

0

Task-based documentation

I’m packing up for the WritersUA Conference with great anticipation. It’s a bit of a busman’s holiday for me. Lately I’ve been immersed in the technical aspects of what I was writing about, so it’s a pleasure to step back from that and think about the art of user assistance in general. If you didn’t…

0

Those pesky computer innards

This was a headline this morning on msnbc.com: IBM says it has doubled speed of computer innards. Of course that got my attention — did IBM really say “innards”? No innards in the story. “IBM has devised a way to triple the amount of memory stored on computer chips and double the performance of data-hungry…

0

Microsoft language, in a cloud

This is only tangentially related to technical writing, but a post by Matthew Stibbe brought to my attention an interesting analysis of Microsoft language over the years. It’s an interactive tag cloud, covering 1976 to 2006, on Todd Bishop’s Microsoft Blog. I dragged the slider back and forth for awhile, first looking to see what…

0

How to write really bad instructions

This evening, trying to assemble a pressure-mounted baby gate for my dog, I picked up several tips and tricks for writing really bad instructions that I just have to share for everyone’s edification: Only name half of the parts in the diagram. Users enjoy the challenge of matching line drawings with three-dimensional pieces and matching…

0

How to add RAM to a laptop

Over the years, I think I’ve replaced just about everything inside my desktops except the motherboard. But I’ve never even peeked inside my laptop. Somehow I absorbed the edict that only “authorized technicians” could touch one. I had this extra memory though. And a great set of instructions. This is an excellent example of good…

0

Bullfighter for writing

Matthew Stibbe’s review of the Bullfighter add-on for Word and PowerPoint intrigued me enough to try it. It’s a quick and easy install that adds a toolbar to the applications. I decided to test it against my most recent doc, What’s New in Data Protection Manager SP1. (If you’re participating in the SP1 beta, you…

0

Learn from nonexamples

I think that content at Microsoft has gotten better over the years at providing examples. Examples are a good thing. What we still tend to overlook are nonexamples. Nonexamples can be as effective, or even more effective, for learning. They provide an extra dimension that adds depth to a concept. Granted, they might be rather…

1

The system tray that never was

In a a recent post, The Old New Thing made reference to terminology errors, citing the system tray as an example. To quote: “One of the most common errors is to refer to the Taskbar Notification Area as the “tray” or the “system tray”. This has never been correct.” We recently had several vigorous discussions…

1

Development, the microscopic view

Whether it’s software or content, making a change can often be a much bigger deal than you’d think. I was reading The Best Software Writing I, selected and introduced by Joel Spolsky, and came across a delightful essay on that very topic. It was from Eric Lippert’s blog back in 2003, and fortunately it’s available…

1

New documentation: that first paragraph

You are transitioning from content design to content development… The framework is ready. You’ve created the document with the main sections that you designed, and you’ve probably dumped in some known information and lots of questions and notes from your design phase. What now? I’m sure every writer has his own way to get the…

1

Looks like a file synchronization solution (Windows XP)

Tristank mentioned a Powertoy that sounded interesting, SyncToy for Windows XP. (An aside…I think it’s odd that back when hard drive space was limited and expensive, I’d download anything that caught my interest…and now that I have lots of inexpensive storage space, I’m much more particular…) The marketing-speak didn’t quite sell me, so I went…

1

IT pros – how do you use worksheets

If you’ve ever used any product documentation that included worksheets, checklists, or other job aids, I’d appreciate your input on two questions. How do you actually use those job aids? And how would you like to be able to use them? For example… I just read them online I print them out and fill them…

0

From list to diagram: modeling workflow

This week’s lesson in the managing content projects class was on modeling workflows. Quite timely too, since I had offered to diagram a process for writing chapters that I hadn’t gotten around to doing. It was a fun exercise. We started by writing out a list of the steps in a process. I began scribbling……

0

Metrics for content development

First off, notice how I used “content development” rather than “writing content”? The reason is that writing is really just a portion of the task, and it’s important to stand your ground on that. Otherwise, non-writers will scoff at your metrics. “An hour for a definition? Ha! I could write one in a minute!” As…

0