Keeping Track of My Tech

I’ve been keeping a couple of other blogs about the stuff I’ve learned using my own personal tech, mostly the ExoPC Slate tablet and my BlackBerry Bold. I find that writing notes about what I’ve discovered while using these gadgets helps me remember how to use them (and I can always go back to my notes when I forget).

But since I really want to drive traffic to my own business site, I think I’d rather post all those notes here. It’ll help keep my notes centralized, and by using the Categories and Post Tags efficiently, they’ll be more organized.

I hope you find it useful!

Posted in My Gadgets, blog | Tagged , , , | Leave a comment

Hiding Information in a Vagueness Cloud

I’m not sure where this idea comes from exactly, but some people seem to feel that writing in a vague, overly-complicated style is more professional than writing in a simple and direct style. I can only suppose this idea comes from a literary background, hearkening back to bored students dozing in their 18th century literature classes.

I once had a friend ask me to write her a strong cover letter for her CV. Her cover letter was a mess of passive voice, $5 words, and six-line sentences that were so riddled with commas, I was surprised the letter wasn’t dripping with fresh blood.

I cleaned the cover letter up, using strong verbs, shorter sentences, and the active voice. When I handed it back to her, she rejected all my changes saying that the simplicity and clarity of the letter made her look unsophisticated.

When it comes to technical documentation,  writing in a clear, direct, and active style should always be the goal. You may find it necessary to write vaguely or passively, but you need to evaluate each case carefully.

Writing in this direct style not only makes it easier to know who is doing what, it can sometimes expose weaknesses in the product you are writing about. If the specifications are written in a passive, vague manner, this often means the writer was unsure of his material, so he tried to gloss it over with vague phrasing, hoping the reader doesn’t ask too many questions.

But when you attempt to rewrite it in a clear, direct manner, you realize that you may need to guess who is doing what to who, and how, and when, and even why. The specs aren’t providing any of that key information; the vagueness of the document implies that you know all of this already (with an unhealthy undercurrent of suggesting you may be dolt for not knowing).

It is in this rewrite in the active style that you can really shine in doing your job. Go find out the answers to these mysterious questions, and not only will your document be stronger, maybe the product you’re writing about will be improved as well.

Posted in Advice | Tagged , , , | 3 Comments

Dealing with Difficult SMEs

No technical writer is an island: although we can research, experiment, and fiddle with the technology to figure out mostly how it works (or how it’s supposed to work), we still need to sit with the developers, the testers, the trainers, or product designers to gain more insight into the product. These people are often fondly referred to as SMEs (Subject Matter Experts).

While most of these people are happy to spend time with the technical writer to share their insight, there are some people who are so pressed for time that they can spare precious little time with the writer. Often times, these are precisely the people you NEED to speak with to get the information you’ll need for your documentation, or worse, perform a technical review of the drafts.

It’s rarely worth the effort to try to convince these people otherwise. There is often a perception in the development community that spending time with the writers is a waste of time (as the saying goes “Nobody reads the Guides anyways!”). The only thing you can do is make the best of the bad situation.

Some would say that any success dealing with SMEs must come on the basis of personal initiative, ingenuity, charm, back-scratching, and arm-twisting. But I’ve found if you tighten-up your interviewing techniques, they’ll be more open to working with you. Sometimes the SMEs are afraid you’re going to take too much of their time, so they’ll refuse to give you ANY time.

Approach the SME and say “I’ve got four questions, so it shouldn’t take more than 30 minutes of your time, and it would really help me out. When can you meet with me?”

When you decide on a time to meet, show up promptly! Ask your questions (make sure they’re specific and well thought-out) and make sure you stay inside your predicted amount of time, even if you actually have more questions.

This shows the SME that you respect his time and his workload. Often, if you need more time with the SME, he’ll spend this extra time with you out of his own generous nature.

And then when you’re done, thank the SME for his time profusely. I’ve found that SMEs are always hungry, so if I found they were really helpful, a cookie goes a long way to secure another question session.

Posted in Advice | Tagged , , | 2 Comments

The Documentia Redesign

We’ve decided that to update the old website to make the First Draft Blog more prominent and easier to access.

And although it’s probably transparent to you, the reader, Documentia has changed webhost provider. The very friendly people at Namespro.ca have earned our trust in the past year, so we’ve decided to move our domain and webhosting to them. We highly recommend Namespro.ca (located in Vancouver B.C.) for all your domain registration and webhosting needs.

Stay tuned for updates and the redesign that will come bit by bit. If you need to contact us at Documentia, please call us at 514-791-3627.

Posted in blog | Leave a comment