Category Archives: documentation

by Scott Nesbitt

So simple it doesn’t need documentation?  Clip to Evernote

For the last couple of weeks or so, I’ve been poking around Google’s Chrome Web Store. Not looking for anything in particular, just taking a peek at some of the apps that are there. Doing that is aimless and mindless, I know, but it’s also kind of fun.

The other day, I took a look at one app. An online drawing program. It looked simple and, for whatever reason, I took a peek at the user comments. One comment really stood out:

Lots of tools, but no help documentation at all. You have to dig into the developer’s site to learn that the software is “currently undocumented’ which I take it means you’re on your own.

I looked at app in question, and it was simple. But only if you’re familiar with that type of software. And even though it’s a common application, not everyone is familiarity with it. They might not know the concepts or even the terminology around it that many of the fives of people reading this take for granted.

Continue reading →

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 DMN Communications

Giving users incentives to contribute to the documentation  Clip to Evernote

Milan Davidovic left a thought-provoking comment on a recent post in this space. It had to do with giving users incentives to learn lightweight markup languages when they contribute community-generated documentation.

We’ve been thinking about that comment, and have been wondering what incentives companies (and free/Open Source software projects) can give users to contribute documentation. We discussed this with Anne Gentle in a podcast a while back, and Anne devoted some of her book to that topic.

But we’re sure there’s more to it than even that. Dru Lavigne touched on some reasons people would want to get involved in a presentation at FSOSS 2009.

So, here’s a question we’d like to throw out to the wider tech comm world. What incentives would you give to users to contribute to the so-called official documentation set? And if you actually have users who do just that, what incentives (if any) do you give them?

Feel free to share your thoughts, ideas, and reality by leaving a comment.

by Scott Nesbitt

Ramblings about lightweight markup languages, user-generated docs, and pulling it all together  Clip to Evernote

As the title of this post states, what you’re reading is the result of some woolgathering I’ve been doing about a topic that I recently discussed in this space. Don’t expect any conclusions or deep insights …

If you’ve been reading this space for any length of time, you know that melding user-generated documentation with so-called official documentation is something that I think about quite a bit. As I’ve written and said in the past, I haven’t found an efficient and effective way of doing that melding.

One of the keys to that could be to use lightweight markup languages.

Continue reading →

by Scott Nesbitt

Wikis, documentation, and aesthetics  Clip to Evernote

Quality content or appearance? My choice is the former. No matter how beautifully laid out and typeset a piece of documentation is, if the information that it contains isn’t accurate or useful fine typography and design can’t paper over those deficiencies.

That said, I tend to lean slightly more to the design and aesthetic side when it comes to documentation that’s delivered on the Web. Adam Hyde of FLOSS Manuals said this to me:

Documentation has to have an aesthetic strategy. Documentation has to be consumable. It has to be friendly, not just in the way it’s written but in the way it presents itself. Publishers spend a lot of money designing books for this reason. I think that documentation should follow the same principles. It should be easy to read, it should look attractive, and it should look like something you want to engage with.

Continue reading →

by Scott Nesbitt

Videos and screencasts have their drawbacks, too  Clip to Evernote

As I’ve written in this space in the past, if a picture is worth a thousand words then a short video or screencast can be worth a thousand pictures. And a well done video or screencast (or series of them) has the potential to ease a user through the maze of a new interface or device.

For the last year or so, I’ve heard more than a couple of people (no, Gordon, you’re not one of them) tout video and screencasts as the future of documentation. While video may have killed the radio star, I don’t think that it’s going to kill documentation as we know it.

Why? Not everyone wants video as their documentation, or even as part of their documentation. They want information now, and don’t want to wait a couple of minutes to watch a walk through of what they need to do.

There are other factors, too. Read on …

Continue reading →