Showing posts with label Technical Writing. Show all posts
Showing posts with label Technical Writing. Show all posts

Tuesday, January 17, 2012

Revenge of the Tab Dump

As always, interesting articles that I indended to write about, but never found the time.

1. I spend most of my professional life working in PowerPoint. Slide:ology helped me to learn how to design better slides. It could help you too.

2. Justin E.H. Smith argues the, to me, obvious point that marriage is work:
One might suppose rather that love and work—or at least a distinctly modern, capitalist conception of work—are two sides of the same coin: both emerge together at the same moment in history, and both carry with them the ungrounded belief that each of us has our destiny in our own hands, that our happiness is entirely a consequence of our life choices, and our misery a surefire sign that we are doing something wrong. In this connection the contemporary use of "passion" serves as a revealing misnomer. For how many can recall that, originally… to undergo a passion was to suffer an affliction over which one had no control? … in the modern world, in both work and love… we are expected to treat the things that happen to us, that cannot but happen to us, as a result of the way our society is structured, as if they were the result of our own sundry projects of self-creation.
He’s a bit too cynical and determinist for my tastes, but there’s some truth in there: many, many people do not hold their destiny in their hands, for one reason or another.

3. I’d Rather Be Writing ponders a good question for all writers.
I was talking with my wife’s uncle last week about writing strategies for fiction, and whether it’s better to outline everything ahead of time, or figure it out as you go. The former is apparently called a “plotter” method and the latter a “pantser” method (called pantser because you fly by the seat of your pants).
He said there’s no right way, but if you’re planning to figure it out as you go, it’s still a good idea to write your last chapter ahead of time. This way you know generally where you want to end up. If you don’t know how your novel is going to end, he said, you often wander around and eventually end your novel in fanciful/unbelievable way. Further, pantsers often lose motivation because they don’t know the point or meaning of their story.
He goes on to connect this to his life as a Technical Writer. I always enjoy his posts; he’s a thoughtful writer who has some great insights in the details of technical communication.

4. AGNI interviews Johnathan Lethem about sampling and creation. I love how Lethem thinks. Some samples:
  • On using quotations in his work: “Girl in Landscape is relatively free of cultural reference. The voice is in the third person omniscient and stays relatively close to a thirteen year old girl who’s not a voracious reader or music listener, who lives in the future, and on this other planet. Yet I know there was at least one moment when some descriptive passage of the desert landscape under the sky slipped into a tiny bit of a Joni Mitchell lyric. It was irresistible, it was like a throb in the voice that just felt right, and there’s no reason in the world why I wanted to resist that. There might have been five words of quotation, but direct quotation, and I just let it be. But that’s notable because it’s so exceptional inside that project."
  • On Dylan and his sources: “This whole question of quotation and theft in Dylan tends to be looked at in arguments in favor for or against his unique genius, as though he himself were introducing the very problem that undermines his own claim. In a way it’s giving him too much credit to call him an original thief. He’s a typical thief. So can we now please just leave that question behind? When an ideology exists, no one is free of it. He’s spent a lot of time defending himself or obfuscating about sources because he has absorbed the same frameworks that people are using to judge the work."

Ultimately, if art is working then it’s done something and you only need to become interested in sources if they interest you. Nothing more needs to be said. When art succeeds it’s its own law, it’s its own reason for being.” I know that the few “original” things that I write almost always spin off of something else that I’ve read, either consciously or subconsciously, and certain phrases that I use have been used in that way before. If this should be called “sampling” so be it – I believe that the modern world is better off for it.

5. The world's smallest known vertebrate. I miss having frogs in the house.

6. Gotta say, a movie called All Watched Over by Machines of Loving Grace sounds fascinating: Adam Curtis, the director, describes it as "...This is a story about the rise of the machines/and how they made us believe/we could create a stable world/that would last forever."

7. In her essay collection In Other Worlds: SF and the Human Imagination, Margaret Atwood splits hairs and describes her Science Fiction - The Handsmaid's Tale, Oryx and Crake, The Year of the Flood - as "speculative fiction" rather than scifi.

8. One of my favorite albums is the Kinks' Village Green Preservation Society, and probably the most rocking tune off this understated album is the majestic "Big Sky." Adam Fieled overthinks the songs implications.

Tuesday, March 30, 2010

Easy = True

Check out Kai Weber's interesting post about the effects of clear software documentation - or failing to produce it. As he puts it: 
According to psychologists, people are more likely to perceive something as true when it’s familiar and hence easy to think about. The underlying measure is called “cognitive fluency”. ...
‘Clear and easy’ documentation is seen as truthful, the product as reliable and the manufacturer as professional. The inverse seems true, too: As the medium is the message, readers struggling with obscure fonts “unwittingly transfer that sense of difficulty onto the topic they’re reading about.”

In my line of work, the editing and/or QA process is neglected in favor of speed or just "getting something out there." This attitude is frustrating on many levels, but the above is even more proof that with bad documentation you reap what you sow.

Thursday, May 28, 2009

Inserting Humor in your Online Training Tests

I've heard arguments like this one before: use humor and fun, hip formats to engage and liven up your training. However, I've found there to be several big drawbacks to this:

1. Humor is subjective. You have to be careful when deciding what is funny, especially for training with a large audience. For example, if your audience is international, any humor you interject might not survive the translation process or, if it does, may not be funny in another culture.

2. Corporate humor isn't funny. Jokes rarely survive the review process. If you need to get approval for your course, jokes that survive past a panel of reviewers are typically the least funny of the bunch. In my experience, the most you can hope for in these cases is a hip irreverent tone that many might read as funny.

3. The format may not fit. The article uses the "Who Wants to be a Millionare" game show as a good example of a quiz, but, if memory serves, the only way to keep playing is to answer all of the questions correctly. The main purpose of an elearning quiz is to get the user to demonstrate that they know the material they've just covered, and you're not going to know if this is true or not unless they get to answer all of your questions.

I'm a big fan of humor and fun formats as much as the next guy, but when it comes to business training, you have to be very careful how you use them or you may find that it decreases the effectiveness of your training.

Friday, May 1, 2009

Writing is Easy... isn't it?

For all of those people that think technical writing is easy, this article is a good summation of all of the other unseen tasks that occur under the surface of any writer worth their salt. With bonus full-color graphic!

In short, even though technical writers are often dismissed as a luxury (and often the first to be let go), the work they perform is indispensable. Try figuring out a non-intuitive application with a help system written by a non-writer and you'll see what I mean.

Friday, February 13, 2009

Blogs as Release Notes

An example of a company using their blog to cover details of their latest release.

Blogs and Wikis are the next generation of user documentation.

Thursday, December 11, 2008

Where is Help 2.0?

I empathize with the ambivalence Tom Johnson feels when completing a help system/manual. Since no one is every satisfied with "the manual" these days, it makes the technical writing job that much less fulfilling.

He references Alan Porter's fascinating Move over DITA – Chaos Is Coming! article, where he realizes just how out of date the current help paradigm is by observing his daughter research for a school paper. The money quote:

"In fact for most of my working life to date, the technology I used at work far out paced that I used outside of work.

But not any more."

It's a sad truth, and one that will mean more painful discrepancies between user's help expectations and companies delivery methods until it can be resolved.

Thursday, December 4, 2008

Minimalist Documentation

Here's a good summary of some of the presentations of the ISTC conference took place in Nottingham, UK, 23-25 September 2008.

In the "Minimalism in complex knowledge domains: can it be done?" section, there's a discussion of minimalist documentation. I've always minimalist idea intriguing, but have never been able to recognize it myself for a number of reasons (software is too complex, need to explain general processes in detail, and the requirement to document around bugs).

However, I liked this:

"Galyna says that minimalist documents should not only contain procedures. Users need more information. As with all types of documentation, two problems that technical authors have are deciding on the level of detail and organising the tasks."

This is the crux of technical writing: you want to provide the steps to help the user solve their problem, but you also need to provide the bigger picture. Galyna's advice seems to be moving away from minimalism, but I think that's almost unavoidable for most application help.