Category Archives: authoring

by Scott Nesbitt

The blurring of the lines between the Web and the desktop  Clip to Evernote

While at a co-working space a few weeks ago, I found myself chatting with a software developer while taking a short break. He mentioned that he’s part of a team that’s developing a Web-based e-learning application. When I said that lines between the desktop and the Web are really blurring, he seemed rather surprised.

Not because he disagreed with me (he didn’t), but because he wasn’t completely sure that anyone else was seeing the distinction between those two world eroding.

And it is slowly eroding. There’s more and more integration and interoperation between desktop and Web applications (not to mention mobile apps, too). I’m not going to debate the merits and the drawbacks of shifting to the cloud, but I do see the barriers between the desktop and the Web being eliminated eventually.

That has implications for technical writers.

Continue reading →

by Scott Nesbitt

Another view of using analytics with documentation  Clip to Evernote

Analytics. It seems to be quite a hot topic in the documentation world at the moment, especially with Web-facing docs. Mark Fidelman of MindTouch even wrote an excellent guest post on that subject for this space recently.

While I think that analytics can be useful, I also think that perhaps they don’t tell the whole story.

The spark for this thought came from something that Anne Gentle recently wrote:

When I spoke with a few Google technical writers at the STC Summit, one of them confirmed that their performance reviews include a web analytics component

OK, so certain topics in Web-facing docs get less traffic than other topics. But does this indicate a problem with the documentation? Or is it something else?

It could be an indication that portions or functions of app are used more than others. Or it could point to features and functions which many people find difficult to use. Yes, it could mean that the documentation is lacking in areas, and people are going elsewhere to find answers.

As I mentioned a few paragraphs ago, we’re not getting the whole story. I’m not sure we can get it, either.

That’s not to say that analytics aren’t useful. They are. And the statistics present (at least) a couple of good opportunities. One is where we can devote more effort to the documentation. Not just traditional manuals and help, but also tool tips or embedded documentation. It can also give us an opening to work with developers and interface designers to improve the usability of a user interface.

Thoughts? As always, your comments are welcome.

Photo credit: mashe from Photoxpress

by Scott Nesbitt

Documentation: the granny figure standing behind you  Clip to Evernote

A while back, I wrote a post in this space about Sugata Mitra and his Hole in the Wall project. The project involved, literally, putting a computer and a track pad in a hole in a wall in several locations in India, and letting children (who’ve never seen or used a computer before) discover and learn to use the device.

I was browsing the BBC News Web site recently and stumbled across an article describing how Mitra not only continued the experiment, but also how he’s been expanding on it.

A paragraph in the article sparked a thought about the role of documentation:

Further experiment showed that having a person – known as “the granny figure” – stand behind the children and encourage them raised standards even higher.

Here are a few thoughts on that idea.

Continue reading →

by Scott Nesbitt

Thinking outside the ToC  Clip to Evernote

The table of contents. I definitely have mixed feelings about it. It’s a classic way of organizing and navigating through information. But I find the beginning-middle-end structure of the ToC to be limiting.

Bruce Lee (yes, that Bruce Lee) often talked about set forms as a weakness of classical martial arts. One of his more memorable quotes on the subject came from a sequence cut from the movie Game of Death:

Rehearsed routines lack the flexibility to adapt.

Let’s take an example from my less-than-stellar attempts at learning martial arts: the typical block/counter taught in many styles. In a real-life situation, it isn’t always the best or most workable solution.

The same goes for the table of contents as we’ve known it since … well, since forever. In some ways, the table of contents is the rehearsed routine of the documentation world. It’s not always the best option in many situations.

Continue reading →

by Scott Nesbitt

It’s only easy if …  Clip to Evernote

As I’ve mentioned in this space before, my daughter Thais has autism. While I’d give just about anything for her to be a neurologically-typical child, I have to admit that helping raise her and deal with her autism has affected various aspects of my life. Both personally and professionally.

At the moment, by wife and I are having a running battle with the school board about our daughter’s placement. We think that Thais should stay where she is, but the board (and at least one teacher) think otherwise.

A couple of weeks ago, my wife was talking with a teacher about the subjects that Thais is strong in, and others that she is weaker in. It’s was a long conversation, but I won’t bore you with the details. The thrust of the teacher’s argument was that my daughter couldn’t learn concepts. My wife asked why, then, is Thais doing well in French.

The teacher, a former French instructor, stated that French is easy. My wife then asked her why neurologically typical kids struggle with French. Of course, the teacher didn’t have an answer for that.

This brought to mind a point I’ve been making for years now: something is only easy if know how.

Continue reading →

by Scott Nesbitt

Is it time to look at documents in a different way?  Clip to Evernote

Originally, this post was going to be about screencasting and audio documentation. But a comment by Gordon McLean on a previous post got me thinking and took this post off on a new tangent. Thanks a bunch, Gordon …

Seriously, though, Gordon brought up a good point. And that point sparked some thinking that I’d been doing for a while about what documents are and aren’t. Don’t worry: I’m not veering off into the world of General Semantics. But I think what we should re-evaluate out preconceived notions about documents.

Continue reading →