wshaffer

One of the work projects that pretty much consumed my work life from last August through this March is now in beta: http://docs.vmware.com.

We made a little video to talk about the project and why we did it: https://www.youtube.com/watch?v=JuFjqkZNF6k

I was woefully underprepared for my Toastmasters Club's "humorous speech" competition today. I'd sketched out the outlines of my speech, but hadn't really had time to practice it or flesh it out. And I'd actually intended to bow out of giving a speech, but my fellow club members persuaded me to give it a go. Then I won the contest by virtue of being the only entrant. So, I'm going to represent my club at a local competition in a few weeks.

Then I gave an impromptu table topics speech that was substantially funnier than my half-prepared speech, so I'm going to use that material in my reworked speech. So when I do go to the local competition, I will actually have something funny to say.

Actually, the experience was very much like workshopping the first draft of a short story, except with the added adrenaline of being entirely unsure whether I could bring my speech to a successful conclusion.

The VMware Information Experience team has started a new video series called Blogger Talk, where we interview VMware bloggers about their favorite topics. I talked to Mike Foley about vSphere security topics like why a VM escape is unlikely on ESXi, how to deal with internal security threats, and how to use the vSphere Hardening Guide.

Please like, comment, or share if you are so inclined.

From a training course on discrimination law:

The law protects not only people belonging to traditional organized religions such as Buddhism, Christianity, Hinduism, Islam and Judaism, but also those with sincerely held religious, ethical, or moral beliefs.

I have spent, I kid you not, the better part of the past 5 work days trying to figure out the source of an arcane publishing problem that results in English language titles occasionally appearing in the tables of contents of non-English-language documents. It's entirely too arcane to go into here. If you will forgive me for being vague, it results from Thing A (which is a little counterintuitive but needs to happen to keep the software usable) combined with Thing B (which is a little counterintuitive but has sound reasons behind it), followed by Thing C (which is basically dumb behavior and in my opinion, a bug).

So, I filed a bug report, where I tried to explain in as comprehensible a way as possible that "We have a problem because Thing A --> Thing B --> Thing C, and I think the solution is to have the software not do Thing C, which arguably it really shouldn't do according to the spec, which I have linked here." The title of the bug, by the way, is basically, "Thing C should not happen."

I got back a "Sorry, why can't you just not do that in the first place? And also, do you want a fix for Thing A, Thing B, or Thing C?"

So I wrote back an even simpler explanation of the problem, with diagrams. And reiterated, "The problem here is Thing C."

I have just been offered a solution that prevents Thing A from happening. Yeah, the one that "needs to happen to keep the software usable." I have just written back explaining why that is not a fix from my point of view, and reiterating, once again, that the problem is Thing C.

I'm starting to worry here that the real solution is going to end up being Ugly Error-Prone Workaround D, which I came up with while I was writing my second bug update, but explicitly nixed because it was a pain in the butt and people would forget to do it correctly and not catch the error until the document came back from translation.

Sigh.

Last night and this morning, I helped two coworkers work through problems with an internal tool that I happen to have written the internal documentation and training for. It looked to me, from what I was able to see in the logs, like the problem was user error - both of them were, completely separately and independently, doing Operation X instead of Operation Y.

Which really made me think, "Gee, how crappy must my training and documentation have been, if it left them so confused? What the hell did I do wrong?"

Until I asked the second colleague, "Hey, why did you do X instead of Y?"

And she replied, "Oh, Y isn't visible in my user-interface."

It's looking like the tool administrator borked up a bunch of people's permissions. Fortunately, my documentation covers what to do in that case.

I have just replaced my increasingly unreliable 13-year-old printer with a brand-new Epson inkjet. It prints, it scans, it copies, it makes a mean strawberry daiquiri*.

Setup was fairly smooth, but when I installed the printer drivers, I got a little popup that said something like, "Print queue was not added. Please consult the User's guide for instructions on adding a print queue manually." So, I found the online User's guide, found its nice search box, and put in "add print queue."

No hits.

Okay. I tried just searching for "queue". No hits.

Scanned through the table of contents looking for anything that resembles adding a print queue. No hits.

Memo to all those software developers out there: if you're going to put text in the user interface of your software telling people to look in the manual for something, please tell the person who writes your manual that you've done that.

* Okay, it doesn't make strawberry daiquiris, but in this weather, it totally should.

A trend I've noticed with some amusement at my place of employment is the use of "feedback" as a countable rather than uncountable noun. For example, "Let's collect all the customer feedbacks into a single document."

Have other people heard this, or is this idiosyncratic to my place of employment?

I just got the results of the surveys that members of the audience filled out at my last conference presentation. 71.4% "strongly agreed" with the statement, "The speaker was effective," while 28.6% merely "agreed". In the written feedback, respondents described me as "a confident speaker," and praised the clarity and efficiency of my presentation.

I say this not just to brag, but because seeing the results brings back a rather vivid memory of the first debate tournament I participated in back in high school, and the evaluation forms the judges filled out. I was a terrible public speaker back then, and I knew it, and the fact that I knew it was obvious in my performance and made it more terrible. The scores on my evaluation forms were justly terrible, and one judge told me that I was so awful that I should quit. There may have been a "for God's sake!" in there. Looking back, I'm kind of surprised I didn't quit - at least not right away. I stuck it out for the better part of a school year before my mom persuaded me that I needed to cut an extracurricular activity from my schedule. I got good enough to win the odd debate, but never got particularly comfortable with it, nor did I rid myself of my conviction that I was a terrible public speaker.

I'm fairly sure I still was a terrible public speaker at that point. I was definitely still terrified of public speaking. Years later, when I started graduate school, they sent someone around to videotape us teaching a lab session, so that we could review the tape and improve our performance. I never watched my tape. I couldn't bring myself to do it, because I was convinced it would be utterly terrible.

Grad school at least rid me of the fear of public speaking. After teaching so many undergraduate lab sessions, exam reviews, doing literature reviews for lab meetings, and surviving my qualifying exams, the mere idea of speaking in front of a group lost its terror. Once an activity stops making you break out in a cold sweat, it's a lot easier to improve it. And a lot more pleasant. I'm not sure exactly when I got "good" at public speaking, but just in the past few years there's been a distinct uptick in how often I get asked to give presentations. That may be some kind of indicator. (I put "good" in quotation marks because there are lots of people who are still much better speakers than I am. I am good enough now that I can give a talk and people will learn something from it and not be bored in the process. I've seen speakers who can hold a room full of people spellbound for an hour. That ain't me. Not yet, and possibly not ever.)

For a lot of the time in my life when I was scared of public speaking, I thought that the people who were good at it had some kind of inborn talent. Or that they were just extroverted, or charismatic, or something that I wasn't. So, if you're also scared of public speaking, let me assure you that that's not true. Public speaking is a set of skills, and you can learn those skills with practice.

And in the unlikely event that anyone out there is a judge for Lincoln-Douglas debate tournaments: Don't ever tell a kid to quit.

So, when I get handed a new documentation project to do, it goes like this. There's a period of weeks or months where I read the spec, I write a doc plan, I play around with the software, I scrawl incomprehensible diagrams on graph paper, and I think. A lot.

And during that whole time, I get an chorus from release managers, developers, product managers, etc. of "Have you started writing yet?" It starts as a gentle chorus, and gradually gets more strident.

At some point, the chorus begins to dent my serene self-confidence that I know what I'm doing, and I am gripped by an Unreasonable Dread during which I become convinced that I've forgotten how to actually write documentation and that I probably ought to quit and do something more suited to my talents, like guinea pig herding.

Then I pull myself together, build a playlist of energetic music, and begin cranking out documentation at speed.

I've been through this enough times to recognize that this is exactly how it works, but I wonder if I'll ever get to skip the Unreasonable Dread. At least it was pretty short in duration this time around: I think it lasted less than 24 hours.

The funny thing is that with fiction I'm very much a "just dive in and start writing" kind of writer, but that really doesn't work with technical documentation.