January 19th, 2006

Feedback to my writing here and in other places has tapered off in the past year. I seldom get emails or comments in my guestbook, and nobody has rated my blog since November. (But I got some nice comments back then.)

But today I got a nice compliment from someone that I've been working with from time to time. She said, "You are such a good writer ... it's always a pleasure to [work with you]." Well, I can tell you those were pleasant words to read—especially considering the source (a woman who has worked with many people in many different organizations at many different management levels).

I glowed with pride after reading what she had to say, and then remembered how I stopped writing to try and "impress" people. That is, I used to write with a set of filters all asking questions like, "what will my mother think of these swear-words?" or "is this too personal?" or "do I sound like a wanker?" (I seem to be particularly sensitive to this today—see below) or "does this make my butt look fat?"

Well, maybe not that last one.

But, anyhow, around the time I stopped feeling apologetic for everything I wrote and started trusting my abilities is when I started improving (note how I said "started" improving ... I haven't finished yet). I have never had trouble with length; in fact, keeping things down to a respectable word count has been the challenge—not finding enough words to fill the page.

I used to irritate my university friends about this: I would complain that I had too much written for my term paper, and I needed to edit it down severely to fit into the word count. At first they would look at me with that slightly-irritated grimace that is supposed to say, "You're busted! I don't believe your self-important wanking bullshit. You're short of your word-count like the rest of us and now you're embarrassing yourself and subsequently embarrassing me by lying about it!" But then when I would pull out reams of pages to show them, their irritation changed to genuine pissed-offedness that I had written so much. So much extra, that is.

It really sounds like I'm wanking when I say that "too many words" has often been my writing issue in life, not "too few words". But I'm not wanking because it's hard—bloody hard—to précis down something that you've written without losing the point or the essence (or the spirit). It's easier to keep adding until you reach your target word count (though quality of writing and focus may be a problem if you find yourself writing that way).

Right, so over the years I've concentrated on learning different voices for my writing. Obviously, I take on a casual, vernacular, almost vulgar tone in these Rant-o-Rama entries. That's just because it's easier and faster to write with the same (or similar) voice that I speak with. When I write short stories, I tend to handwrite them into a notebook because the tone "needs" to be much more narrative and I find a slower, more pedantic way of capturing the text gives my brain enough time to catch up and overtake my writing so that I can think a sentence or two ahead.

On the other end of the spectrum: technical writing is a matter of revision and more revision. There's absolutely no art to it, which is why I can listen to music while I'm authoring technical content. To get into my zone about writing user-level docs, I make myself feel kind of bossy, then I get down to work:

  1. Click File > Open. The Open File for Edit dialog appears.
     
  2. Select the file you want to open and click OK.
    NOTE: DO NOT double click the file, as this is not listed in the Use Cases the Project Manager wrote.
     
  3. Type the sentence, "Chihuahuas are evil and should be eradicated from the face of the Earth."
     
  4. If you asked "why?" or think this is stupid, write the sentence from Step (3) fifty more times on the blackboard.
     
  5. Don't talk back. And wipe that grin off your face before I set our rabid pack of sales reps upon you.

Well, unless I am writing reference material for developers, in which case I have to pander to the 10% who still wander around with their macho attitudes. That is, don't tell them what things mean, just use the most arcane jargon so that they can feel like everyone respects them and is in awe of them for knowing what all those bloody three-letter-acronyms (TLAs) mean.

It's true: The "free-spirited wanker" ones stroll the Earth muttering jargon they learned three hours ago with disaffected looks on their faces because they think they look smart and competent ... when really all the other wanker techies are too busy worrying about how they look saying all the jargon themselves. Most of us have our heads down and are too busy to care. The worst—the absolute bloody goddamned worst—are those techie wannabes who learn their jargon one word at a time and use their newfound vocabulary sequentially; that is, they learn a new word such as, say, "orthogonal" and then overuse it for the next two weeks by sending out emails with that word in them, spouting the new word in meetings, writing it into some crappy little white paper they think they are writing .... And gawd help us all because they aren't just trying to sound and look clever, informed, and competent ... they are trying to convince themselves of it as well! And they aren't. In fact, they are pretty dense but they never get it. I don't write well for that crowd, but that's okay; there are a lot of hacks out there who are very well suited to writing for that particular level of stupidity.

Me? I do better with technical docs:

The SlargaBarg interface provides access to the PoultryPicker UI. Using this interface, you can show or hide the IDF, create a new ELM list tab, and read the contents of the QWW. Key points to consider:

Code sample:

// BIF the BAF
if (HoldTheOnions >= ClownCount(OffSet6)) {
    var DeskBlotter = ShaveThePorcupine(Zeus, EMFLevels, 37);
    var TubeSocks(ChiliDog) = StringDup * MoogaMoog(DeskBlotter) + 2.9;
    }

// Now HAV our CAK and EAT IT2
while (klag |= CurdsAndWhey.count) {
    IrritateUser(ActivePuppy.WheelWell(PowerTrip.item(klag).Color);
    klag++;
    }

... or whatever ...

Before I went off on a wild tangent, I was mentioning that I adopt different personas for the different kinds of writing I do. And by adopting the same attitude that some of the "lone gun-slinger" developers like to carry around with them I appeal to them enough that the documentation might actually get looked at. It's pandering, for sure, but the steady stream of developers' attitudes has worn me down over the years. When it comes to (only) development reference material, I just do it the way they want to see it, and ignore issues of clarity, structure, and cohesion with the rest of the doc set.

I punish them for it by making the manual 800 pages. Heh heh heh ...

Rate my blog - Sign my guestbook - Email me - Go back to index