Words and Software : User experience

Visual Basic 2008 Express: Build a Program Now! sample files

Jeanie Decker — Wed, 18 Nov 2009 23:04:00 GMT

I decided to try to learn Visual Basic, so I picked up a book that looked promising: Microsoft Visual Basic 2008 Express Edition: Build a Program Now! I've been working through the chapters. In chapter 6, (adding a splash screen) it instructs you to replace the default icon with one from the companion files for the book.

Time to go out and install them, so I flip back to the start of the book to the instructions. The book says to download them from http://www.microsoft.com/mspress/companion/9780735625419. Dead link. I did a search, it pointed me to that same URL. Fortunately, search also surfaced a discussion thread where someone else was hunting for this download and someone else replied "Look here and click the "Companion Content" tab!".

So I thought I'd share.

Writing good technical documentation, part 3

Jeanie Decker — Wed, 22 Jul 2009 07:45:00 GMT

(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 e-mail in the first page of the Word document. I look forward to getting to know your work."

He estimates that he has about a 75% success rate (not bad!) but would like to improve it. Enthusiastic commenters offer numerous suggestions for rewording the instructions, and at least one of them mentions that it's like technical writing, which of course caught my attention.

Technical writing is full of procedures (or instructions, if you prefer that term). From my perspective working on server products here at Microsoft, the main purpose for the documentation is to help you do something with our product, and quite often the means is a "how to" procedure.

How can you go wrong with procedures? Well, the obvious answers are missing steps, having the wrong steps, using jargon that doesn't match what the user sees, and so forth. But a procedure can be methodical and precise and accurate, yet still not meet the user's need, if it's missing the "why".

I'll use one of my own topics (where I failed on "why") as an example:

Vendors might periodically update a management pack. When a management pack is updated, the version number incrementally increases. You can check the version number of imported management packs in Operations Manager 2007.
To check the version of a management pack...(procedure follows)

Version number can change, you can check it -- but why do you care whether the version number changed or not? What good is that knowledge to you? I haven't given you any idea when you would want to check it or how you should know to check it or what to do with the version number once you have checked it. All of that belongs in "why". (Meanwhile, I've sent myself a note to update that topic.)

Awhile back, in one of those team-building type workshops companies love, we did an exercise where one person had all of the instructions and the other team members had pieces of information. The "leader" had a goal to accomplish that required coordinating all of those pieces of information. Our team was the first to finish, but every member stated that it would have been a lot easier if they had been told what the goal was and why they were doing certain things. (That stuck with me all this time because I was the person who had the goal and failed to share the "why" with the team.)

An adequate procedure tells you "how to". A good procedure tells you "when" and "why" and "then what". Which brings me back to Nathan's post. When I read it, my first thought was that he should tell the writers that he reads their submissions in his Kindle and that is why he needs the query in the partial -- if I understand the why, I'm more inclined to cooperate. Since several commenters made the same suggestion, I refrained from adding to the thread there and hijacked the thought into a post here instead.

Submit questions for the Operator's Manual

Jeanie Decker — Tue, 09 Jun 2009 20:14:00 GMT

There are two ways to approach content on using the Operations console and Web console for Operations Manager:

Explain what information is available in each section of the consoles.
Take examples of information that an operator would want to locate, and tell them how to find it in the consoles.

I've decided to do it both ways, in a guide that I'm putting together for new Ops Mgr operators. Here are a few questions for #2 that I harvested from an email discussion:

I have added a Management Group in the console and I also added few computers, how do I know if these computers belong to the management group that I added?
How do I know if a management pack is applied or connected to the servers that I added in the console?

What other questions might an operator want to answer in the console? Submit your suggestions to jdecker AT microsoft DOT com!

Is your IE8 slow to open a new tab?

Jeanie Decker — Wed, 03 Jun 2009 23:44:00 GMT

Whenever I would open a new tab in IE8, whether by control-clicking a link or simply clicking the New Tab tab, everything would go dead for a good 10-20 seconds until IE8would finally show a new tab and then begin trying to open something in it. (Yeah, it always feels like longer.) It finally began bothering me enough that I started searching for a fix.

The first suggestion I came upon had to do with the restricted sites list. Checked -- didn't have one.

The second suggestion was to run regsvr32 actxprxy.dll. Tried it -- no improvement.

(That doesn't mean that either of those fixes are wrong, it just means I have some other issue.)

I finally came across the fix that I needed in the comments to a post criticizing that second fix above. Add-ons! Clicked Tools -> Manage Add-Ons and there it was: ZuneIEPlugin.ZuneBHO, with a load time of 7.62 seconds. I disabled it and voilà! My tabs work nicely again.

If you too suffer from sluggish tabs, try those three suggestions and hopefully one of them will work for you as well!

FizzBin for geeks

Jeanie Decker — Sat, 21 Mar 2009 09:09:00 GMT

Scott Hanselman has a suggestion for tech support -- a codeword that clues in the help desk that you kinda know what you're doing. I'm not sure fizzbin will catch on, but it's a nice dream...

Writing good technical documentation, part 2

Jeanie Decker — Tue, 10 Mar 2009 06:54:00 GMT

(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 -- or can be -- one of the technical writer's best tools.

By coincidence, my manager recently asked us to jot down what we considered to be characteristics of a good spec for a software feature (from a writer's POV). My contribution:

What it is
Why it is
What it does
How it works
When it does it/is used
Who uses it

That's not too much to ask for, is it?

If you're the writer and you're not involved in your team's spec reviews, ask to be included. Read the specs, ask questions, make suggestions. Remember, whatever they develop from it, you'll have to explain to the customer.

(As a side note, that brings to mind one quality that a good tech writer must have -- the willingness to ask "dumb" questions. If you don't ask the question because you're worried that it might make you look silly, you're doing yourself, the customer, and the team a disservice.)

Back to specs. The spec sets the stage for the story that your documentation will tell. From the specs, you should be able to start crafting the high-level design for the docs: what the user will be doing and what they need to know to do those things, what method and organization for the documentation will be most useful for that type of information.

If the specs you work with don't include user interface mock-ups, finagle your way into those UI meetings and reviews as well. Look at each screen with the question "how am I going to explain this?" Be the customer's advocate: "Why am I clicking Next three times?"

Writing good technical documentation, part 1

Jeanie Decker — Wed, 07 Jan 2009 09:40:00 GMT

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 context:

Ideally, good technical documentation tells you everything you want to know and doesn’t tell you anything that you don’t want to know.

The key in that statement is you. Whether the content is good, whether it answers your questions, whether it avoids wasting your time with irrelevencies...all of those are defined by you, the reader.

Just about every book/class/seminar/workshop on communicating effectively starts at the same place: know your audience. Why? Because I have to know who you are so I can figure out what you'll want to know and what you don't want to know. It's really easy when it's 1:1, like when I write up instructions for a relative.

There are just too many readers in the professional world, though. So technical documentation tends to become "everything anyone might want to know" because we usually prefer to offer at least some value to many rather than great value to just a few.

So, the first best practice is to define your reader (customer, user) as best as you can. To document software, I consider the two main questions to be:

What does your reader want to do?
What does your reader already know?

To answer the first question, you need to learn about the problem your reader has that he wants to solve, about the environment he'll be in, and about his expectations for a solution. All of this information helps you define what the reader wants to know and, in combination with the answer to the second question, helps you define what he doesn't want to know.

Your answers to the questions may also reveal that you have more than one type of reader. Take Operations Manager, for example. We have customers who want an efficient method to monitor many servers. We also have customers who want an easy way to create their own custom monitoring solutions. Some of those customers are support technicians who want documentation that will help them monitor and some of those customers are developer-types who want documentation that will help them create customized solutions. So right there we have two very different readers who need distinctly different documentation.

When your readers have different goals and different levels of knowledge and experience, don't try to write to all of them in one document (if you can avoid it).

I'll be honest, we're not fully there yet with Ops Mgr. Some of our documentation tends to skirt between those two readers. We recognize that we've muddied the waters a bit, which serves neither reader very well, and we're working on repairing that problem in future versions.

MP guides online: a question for you

Jeanie Decker — Wed, 27 Aug 2008 22:20:00 GMT

This is a question about the root page for the two management pack guide libraries (operating system guides and server guides). All of the guides are listed in the left navigation pane, beneath the parent page:

In addition, when you click the parent page itself, the guides are listed and linked on that page:

The question is: does the list on the parent page ("Guides available in this section"), which mirrors the navigation pane, add any value for you? If we removed the links from the parent page and you had to use the navigation pane instead, would you care?

I'd really appreciate your opinions, either by leaving a comment here or emailing mpgfeed AT microsoft.com.

An operating system, a horse, and transparency

Jeanie Decker — Fri, 15 Aug 2008 19:43:00 GMT

Catching up on my Microsoft-related blog feeds this morning, I counted at least a dozen blogs announcing the new Windows 7 blog -- some rah-rah posts, some just passing it on, some speculating as to how much information the blog will actually provide, plus some conversations on the pros and cons of transparency.

Coincidentally, last night I came across an example that illustrates when transparency is the best solution for a situation.

You see, the town of Hickman, Nebraska has made national news because they want to evict an old horse from city limits. I'm guessing that they've been inundated with queries, complaints, and accusations as a result. So, they turned their city's homepage into a timeline of events to explain the situation to all of us who probably couldn't find Hickman on a map and have no intention of moving there but feel it's our business whether the horse stays or goes. (You can probably tell that my sympathy has shifted toward the town's side...)

In my aspect as a customer, I'd be fascinated by similar disclosure about a product in development. But I can also imagine reading "Discussed flippeting the gibbet. Decided it wasn't feasible in this timeline." and being disappointed, because although I'd never had cause to flippet a gibbet before, now that it had been suggested and taken away, I wanted that feature back!

System Center Content Search

Jeanie Decker — Wed, 30 Apr 2008 07:35:00 GMT

I'm not a gadget-y sort of person. I mean, I like gadgets, but I've grown wary of them (both offline and on) because so often they're a disappointment -- either they don't deliver or I don't really have a use for them.

But recently I saw a presentation on a gadget that delivered the exact functionality that I've wished for numerous times: the ability to search just the System Center content on TechNet. So many times I need to look for technical content, and not just the information but the information as contained in our official documentation.

And now some folks have delivered with the System Center Content Search gadget for the Vista Sidebar. I installed it last week and have had to use it numerous times already, and :::drumroll::: it delivered exactly the results I needed every time (and usually as the first hit).

System Center Content Search was announced at MMS this week, so I waited till after the announcement to post about it (and to make sure it was worth recommending).

How not to write a user manual

Jeanie Decker — Tue, 22 Apr 2008 05:52:00 GMT

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 useful.

The key to manuals and instructions is who you are writing for. If you know how to play Pong, you don't need those instructions, so the instructions must be intended for someone who has never played it. But if you've never played Pong, you still don't know how. "Avoid missing ball" gives me no idea how to manage that feat.

Less is not always more.

My new Zune

Jeanie Decker — Fri, 16 Nov 2007 07:12:00 GMT

It's red. A really deep, rich red. Small and slender, but it feels nicely solid. And here was my setup experience:

I had an existing instance of Zune (from the first release), not paired with a device, that I had already upgraded to the new software. I connected the red Zune. The software immediately announced that I needed to update the device. Made the appropriate clicks and the update began. Five minutes later, it was done. I gave it a name (Dora, if you're interested, after the time-traveling spacecar in Heinlein's Number of the Beast - explanation later), set my synch preferences (manual across the board), and it was done.

The reason I got a flash Zune was to dedicate it to old-time radio shows; I have several hundreds of hours of them on CDs. (Listening to radio shows from the 1930s and 1940s is like traveling back in time...hence, Dora!) What made the new Zune perfect for that purpose is the podcast category, which provides a "resume playing" functionality that isn't in the music category.

I transferred a handful of CDs to the folder I'd told Zune to monitor for podcasts -- just a copy in Windows Explorer, since each episode was already an .mp3. I made a folder beneath for each program, and put the episodes for each program in its respective folder. Again using Windows Explorer, I changed the genre of all the files to "Podcasts". Opened the Zune software and almost instantly it had added all of the episodes to my collection, properly grouped into programs. So far, so good.

Next, I reconnected Dora. I dragged each "podcast" (program group) to the device icon to synch. Synch happened way too fast, so I checked the contents on Dora and discovered that only one episode of each program had synched. After trying a few things, I made it work by opening each program in the software, selecting all of the episodes, and dragging them to Dora. It was a few extra steps, but not a major pain because it let me continue to drop more while it was synching the first batch.

Stepped away for a few minutes while synch continued, and when I came back (maybe 10 minutes later), it was done. Disconnected Dora, connected her to a set of speakers, and began playing a radio show. Very cool!

The new Zune is definitely optimized for the scenario where you just want it to work. Put your files (music, video, etc) in the right place and Zune does the rest. So as I'm copying the radio shows over, I take the time to ensure all of the metadata is the way I want it (using Windows Explorer and MediaMonkey) before running Zune to add it to the collection.

Web vs. print challenges

Jeanie Decker — Fri, 07 Sep 2007 20:12:00 GMT

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 whether it would be better to promote the topics and demote the server types:

Server prominent	Topic prominent
Exchange Servers General maintenance Using Windows maintenance tools	General maintenance Using Windows maintenance tools Exchange Servers

I go back and forth on the final organization. But based on conversations with customers, I decided to go with the server-centric organization - thus, a DPM admin who is working with protection of SharePoint servers can find all of the operations content in a single SharePoint section, even if some of that content is the same as in the SQL section or the file server section.

But what I'm considering doing is adding a new section that promotes the topic, as in the table above, so "Exchange & Windows maintenance tools" has two homes. If you're browsing the TechCenter navigation tree, looking for guidance on using chkdsk on a protected Exchange server, you could then find it by going in through the Maintenance node or by going in through the Exchange node.

If I do that and you download the final Operations Guide as a file, it would contain an awful lot of redundancies. But if I optimize for file format, that's really not effective for the discoverability and navigation challenges of the web presentation. So I figured if I wrote it up for this blog, I'd reach a final decision by the time I got to this point.

I'm thinking about it...

A new Vista trick I learned

Jeanie Decker — Mon, 30 Jul 2007 23:08:00 GMT

The Off Campus blog brought to my attention the coolest Vista trick I've learned yet - resizing screens on the fly. Up till now, I thought my only choices were (1) changing the screen resolution, (2) messing with IE's View settings for web pages, (3) Windows's Magnifier. All of those are just a bit too much trouble for occasional instances of too-fine print. And now I found out that all I need is the control key and my mouse wheel - too cool!

Goodbye, hard drive

Jeanie Decker — Sun, 22 Apr 2007 08:15:00 GMT

It started with a funny little error message, waiting for me when I flipped on my home monitor after work yesterday. "Could not write to F:\ms$t"

Well, there is no such directory on F: (an external hard drive), nor should anything have been writing to F: -- click OK and confront the frozen screen. Can't even evoke Task Manager. Reboot.

Safe mode wouldn't start. Windows XP repair couldn't get very far. I finally got it started by shutting down the external drive, and then to be safe, restored the system to a few days in the past. (I do appreciate System Restore.)

I have to confess, though...about a week or two ago, I noticed a few odd sounds coming from the external drive. "Hmm, I wonder if that means it's going to developing problems?" I even thought. But did I do anything about it? Hmpf...

Everything else was working fine, so I powered up the external drive again. No problem until tonight. This time, when the odd sounds began, I dove for the power switch. Maybe F: can be survive, maybe it's just having a bad week, but all of my important data is on it, including my backup files.

I ordered a new external drive (320GB for $99, very nice). I'm crossing my fingers that F: will give me just a little bit more time -- time enough to hook up the new drive and copy everything over -- before it fails completely. No power till then, my old friend.

With that niggling worry in the back of my mind, I decide to catch up on the blogs.technet feed, and I come across "Why can't it 'just work'?" by Chris Avis. At a time like this, how I can sympathize with that!