Documentation and the Case for Better Navigation

online_vendor_documentation

Some of these ideas are from Mark Baker’s blog, Every Page is Page One.

The first challenge of documentation is to get the user to use the product. It doesn’t matter how usable it is if it is so off-putting in appearance that no one tries to use it.

Some of the things we document are complicated, but it doesn’t mean that every individual task, feature, or concept needs to be complicated. Throwing all the content in the user’s face when they look for help with something simple is distracting. It only serves to discourage users from trying and learning.

Take the classic tri-pane help system. It may be full of utility–multiple ways to view and navigate the content, multiple buttons to push to move around it in different ways. But, it screams “Look how big and complicated I am. Look at how many pages there are. Look at how deep they are nested. Look at all these controls you will have to use to navigate me!”

A PDF is far less usable than a well-organized online help system, but it is actually clearer. It presents a single pane and a search box, and everyone knows how to use a PDF. Videos are even better, but they are lousy for many tech comm tasks — tedious, impossible to navigate, impossible to search, impossible to use for reference— but their entire interface is a single triangular button. No wonder users ask for PDFs and videos even when they are not appropriate or usable. They just look so much better.

With the web, the user is not restricted to a TOC or index — you can offer relevant links on every page that allow them to move effectively through the content without ever being aware of how extensive it is or how complex the product is. If they want to explore any of the topics, they can do so simply by clicking a link. Each topic is a navigation hub.

Adopting this view of organization is important because as our content becomes larger and more dynamic, it becomes more and more difficult to navigate using a fixed table of contents. Seeing everything at once is too overwhelming or general, and artificially segmenting it is too confining.

With the web model, you can create documentation that looks simple while remaining thorough and comprehensive in the depth of its coverage. This way, you can have a large information set with manageable navigation at every point, but still have the ability to travel very far across it.

 

Here’s How Shane Snow (Founder of Contently) Writes

ShaneSnow

The following is an interview with writer Shane Snow, co-founder of the high-end brand publishing firm Contently, as told to Copyblogger.

About the writer…

Who are you and what do you do?

I’m Shane. By day, I help run Contently, which I co-founded in 2010. By night, I attempt to commit journalism and, occasionally, urban exploration.

What is your area of expertise as a writer?

In descending order: Technology. Business. Media. Science. Pizza.

Where can we find your writing?

Journalism: shanesnow.contently.com

Blog posts: linkedin.com/today/posts/shanedsnow

Book: sha.ne/Smartcuts

The writer’s productivity…

How much time, per day, do you read or do research?

I spend more time reading than probably anything else. Unfortunately, most of it’s email. I try to read something every night before bed, and I’m always reading while on the train. Research happens in bursts. Or on neurotic impulse, like when you decide you need to know how they get the caffeine out of tea to make decaf.

Before you begin to write, do you have any pre-game rituals or practices?

I usually try to find a place where I can be alone. Sometimes in public is the best place to hide. I also try to write immediately after exercising, as I find some of my best ideas pop out then.

Do you prefer any particular music (or silence) while you write?

I listen to a single song on repeat over and over again to simultaneously create psychological movement and white noise. Currently, I’m about 500 plays into Timbaland’s “The Way I Are” and am considering finding a new track.

How many hours per day do you spend writing (excluding email, social media, etc.)? When is your most productive time of day?

Between two and 20 hours, depending on the day. Usually early morning or late night. Or late night turning into early morning.

Do you write every day or adhere to any particular system?

When I was working on my book, I wrote every morning from 6:00 a.m. to
8:00 a.m., and every evening from 8:00 p.m. to 12:00 a.m. for 12 months. Otherwise, I usually just schedule a few hours depending on the writing project. Saturday is almost always a marathon writing day.

Do you believe in “writer’s block”? If so, how do you avoid it?

I haven’t experienced it. But I also write nonfiction. The story is already there. You just need to find it and tell it. Fiction seems really hard.

The writer’s creativity…

Define creativity.

Going to unexpected places.

Who are your favorite authors, online or off?

Jon Ronson’s writing makes me so jealous I want to quit. And I would kill to have lunch with Oscar Wilde.

Can you share a best-loved quote?

“Prepare to put mustard on those words. For you will soon be consuming them along with this slice of humble pie, that comes direct from the oven of shame, set at the gas mark ‘egg on your face.” ~ Richard Ayoade

How would you like to grow creatively as a writer?

I’m jealous of writers who have distinct voices. I’d like to develop that.

Who or what is your Muse at the moment (i.e., specific creative inspirations)?

Ryan Gosling. Okay, that’s a joke. But I like the guy.

What makes a writer great?

One of my favorite editors, Paula Span, used to say, “Great writing speeds you along.” The best writers in the world are those who can whisk you through 1,000 words in what feels like 10 seconds, or 100,000 words in 30 seconds.

The writer’s workflow…

What hardware or typewriter model do you presently use?

There are about seven antique typewriters laying around my house right now. All seafoam green. But I write on various Mac devices.

What software do you use most for writing and general workflow?

Evernote for research and drafts. Google Docs for docs. Various surfaces for notes, including the whiteboard wall to the right of my desk. At present, there is a paper plate on my desk with notes all over it from an inspiring conversation in my office kitchen. My co-founder, Dave, recently called it, “The Plate of Knowledge.”

Do you have any tricks for beating procrastination? Do you adhere to deadlines?

No. Though I hear amphetamines help. Too scared to find out. Deadlines are sacred, so I try to file early whenever possible.

How do you stay organized (methods, systems, or “mad science”)?

My favorite system for reporting is to record interviews in Rev (in-app or upload to Rev.com), which sends audio out for automatic transcription, and then to beam that directly into Evernote.

When I write notes, I make little checkboxes next to action items that occur to me during a meeting. I periodically go through my notebooks and check off the boxes, usually when it’s way too late.

How do you relax at the end of a hard day?

Sleep.

Just for fun…

Who (or what) has been your greatest teacher?

I had a high school teacher named Mr. Lemons who cared so much that it had a really big impact on me. When his wife got cancer, he shaved his head so they could be bald together. Everyone should love people the way that guy did.

What do you view as your greatest success in life?

Being a good person. Hopefully I’m not failing too badly at that.

What’s your biggest aggravation at the moment (writing related or otherwise)?

Editors who assign stories and then don’t get back to you for months after you file. Makes me want to lose my mind. And yes, this is happening to me right now.

Choose one author, living or dead, that you would like to have dinner with.

Oh man, I said this already. But I’m going to use this as an excuse to pick a second: Douglas Adams. That would be an amazing dinner.

If you could take a vacation tomorrow to anywhere in the world, where would you go (cost or responsibilities are no object)?

I’d probably go back to O’ahu, where I used to live. Go surf with friends, then for a swim at Cockroach Cove.

Can you offer any advice to fellow writers that you might offer yourself, if you could go back in time and “do it all over?”

Read as much as you possibly can when you’re young.

Is there anything else you’d like our readers to know?

My first book came out September 9. It’s called Smartcuts, and you should totally get a copy or something.

Please tell our readers where they can connect with you online.

On Twitter, @shanesnow, or ShaneSnow.com

Words on a Website: Microcopy

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

microcopyimageThe words used on a website are becoming increasingly important, especially when it comes to the user experience. Words set the tone, voice, and brand personality of a site. It’s not just where the words are placed and how they are displayed, but what they actually say. This is called “microcopy.”

Microcopy is the smallest bits of copy in a web interface. It’s the label on a form field, a tiny piece of instructional text, or the words on a button. Microcopy is contextual. It can deliver the right message at the right time and place. It can answer a specific question and address concerns people might have. It’s powerful because it affects the information flow of a website.

The little words and phrases that make up microcopy can add personality to a brand. For example, if you fill out a form incorrectly, the error message you get when you click Submit might say something like: “Oops, looks like you forgot to add your first name.” It’s a lot more friendly than “Invalid field.” The message should provide enough detail so people know exactly what to do, but not so much detail that the information is difficult to process. You don’t want to risk confusing users as they try to accomplish something. Keep it short and sweet.

Another example is the words on a signup button. Rather than saying “Sign Up,” you could say “Sign Up for Free.” By adding just two more little words, users might be more likely to join the site. In addition, the sentence above the button might say “You can unsubscribe at any time.” This microcopy is both informative and reassuring, alleviating concerns of potential customers.

So, think about what those little words on a website mean to the people who use it. You want their experience with the site to be a positive one.