A Guide To Making Friendly Documentation

A good friend is supportive. Non-judgmental. Helpful. They’re there when you need them. I don’t know about you but doesn’t this sound like the kind of thing that would very much apply to good documentation?

What does good documentation do anyway?

  • When new users get lost in the details of figuring out how an unfamiliar system works, leaving breadcrumbs can help them find their way back to the basics and walk them through it, slowly this time, and at their own pace.
  • Sharing helpful tips is one way we build a community on-line.
  • Showing lessons step by step helps people learn to trust themselves as their build their skills, and develop a sense of self-reliability and accomplishment.
  • Giving strong sources lets people do additional research on their own and strengthens your position as a generous source of reliable, trustworthy information.
  • Showing people the evolution of your products — in updates and build specs, or versioning data — helps them understand what changes have taken place and can assure them that errors and bugs have been addressed.

In short: good documentation shares helpful information.

User-friendly is such an worn term that you probably glossed over it in your reading. Didn’t the term “friendly documentation” jar you a bit and make you imagine something different? That little dissonance can help you reconsider the documentation you have on your website for customers who buy your products, people who are in need of your services, or simply those who can stand to get something useful out of what you’re choosing to share over the web.

Points to ponder

The internet helps all of us get connected, but we still need to find ways to talk to each other with clarity, eloquence and authenticity. Not only do those things take practice, they can also task us to write or talk in ways we aren’t very familiar or comfortable with. Lessons and tutorials can help with that.

The internet is a very big place, and it’s far too easy to run face first into too much information. We need a fast way to assess, simplify and narrow down the information that can truly help us do what we need or want to do.

Whether it’s a simple checklist, a full-blown analysis through infographics, side-by-side pictorial or textual comparisons, or simple pictures and instructions underneath, the way you share your knowledge helps the people looking for that kind of clear explanation.

The internet has a lot of information sources, leading to massive pools of conflicting information, propaganda, misinformation, and unsubstantiated, unproven ‘data’, ahem.

To give excellent documentation means providing impeccable data that will stand for itself. Establish a reputation for this and you’ll be well on your way to being a trusted authority.


Questions to help you think about how you approach your documentation:

  • How soon after a product upgrade, for example, does your documentation reflect and accommodate the changes in the product? Do you prepare your customers with links to changes and bug-report fixes that the upgrade addresses?
  • How do planned changes affect the learning curve of new and old customers, and how you help them adjust?
  • How clear and concise are your instructions? Are there screen-shots to help ease the way? What about videos?
  • How is your documentation optimized for different platforms?
  • Have you checked links for active sites and link-rot?

Of course, for every message there is an intended audience:

  • Who are you trying to be friendly with? Who are you trying to help?
  • How do they usually get to you — via what platform (browser, OS, social media, etc.)?
  • How do you know if your documentation is helping them? Is there a feedback or a rating system?


How is the fit between your market and your documentation?
Think of the people most likely to need help with your documentation. Is your market composed of baby boomers? You have to pay special attention to the readability of your articles, from font, size, spacing and contrast to lay-out and design. Jakob Nielsen, pioneer in web design and usability, addresses related issues in:

He also studied how to tailor websites for a teen audience and for motor-impaired people who can’t use computer mice in:


Documentation is everywhere, really. Your website is a portal to your place on the net. Interested people stay and look around, passersby browse and leave — unless you came up with an easy bookmarking function that lets them mark your site for future visits. And of course provide a sign-up service so subscribers know when you’ve come up with something new. 😉

Customers have you as their go-to guy for the thing you do that keeps them coming back. Some may sign up for a newsletter — and that can provide documentation too.


The information you choose to share on your website must serve a purpose: to help people looking for answers is an essential goal. One of your essential goals is to provide documentation that does what it’s intended to:

  • Help someone understand how to do something correctly
  • Share the best way to get something done so they can continue working on their own goals.
  • Explain in the clearest way how they can help themselves with a particular problem.
  • Show them an easier way to do something they’re having issues figuring out.

Your customers have a goal and are encountering issues on the way. Whether it’s tips and short-cuts, intricately involved diagrams, a set of calculations, etc., your the goal of your documentation is to help them to get to their goals.

Friendly documentation helps grow trust and establish strong relationships with you customers. It lays the groundwork for community, authority and interdependence and no matter how you look at it, that can only help your business grow stronger.

Like this article? Found it helpful? Bookmark Jrox Blog for more helpful articles, and visit Jrox.com to learn more about Affiliate Marketing and get access to your own Affiliate Software and eCommerce Shopping Cart.