Storytelling techniques for product documentation

Is storytelling the same as writing well? How to write a concise yet interesting API guide? Is there a way to keep a help system offhand and casual without using humor? All this and much more in my presentation!

doc focus

Color theory: the mystery unveiled

Today I want to share with you a brilliant post covering all the basics that an Information Developer should know about how colors work, brought to you by Dave Gash, a Technical Writer at Google.

In a nutshell, it’s a great read—both fun and educational—that explains how colors work. It’s all there – physics, optics, additive and subtractive color systems, hexadecimal arithmetic (!) and, most importantly, demonstration of how it all works together in real life (I mean, in a real-life CSS).

Believe it or not, CSS color codes really are intuitive. You’ll be surprised to see how obvious it is that “#000000 can’t be anything but black“, and “#ff0000 cannot possibly be anything but bright red“. On top of that, there’s a quiz, real-life CSS examples, and links to useful resources and tools, which all adds immensely to the post’s educational value.

Thanks to the author for gathering all this information and presenting it in such a fun and easy way! That’s rock’n’roll, folks.

View at


Future starts now?

Most of our clients’ needs have gone way beyond traditional single-sourcing scheme: write once, generate different outputs in different formats. Don’t get me wrong, we still are the proud owners of User Manuals and Help Systems. But.

Meeting the business demands, the companies have developed an internet of systems that require sophisticated and strategic information management from us, information professionals: CRM, Feedback Management, Support Center, Help Systems, Knowledge Base, embedded user assistance, and packages of miscellaneous documentation.

That’s the reality, but what’s next? The amount of the information is exciting, and some experts envisage that the excitement will turn into shock pretty soon.

The article written by Ray Gallon and Andy McDonald lets you visualize the information management and helps stay prepared.

Meet and greet – age of molecular information is here?


Content Readability: Wanna Do the Maths?

All technical writers struggle to develop documentation that would be easy to digest by both advanced and novice users. Nowadays, when a 5-year old can download a game on Play Market, start it, play unless getting bored, and delete it, and a 60-year old can get confused by the amount of freezer controls located on the dispenser panel, it’s an uphill battle. We do have to write documentation that would suit both types of users.

Continue reading


Domain awareness against the curse of knowledge

Recently, I came across the article “Seeing things from the perspective of a learner by Tom Johnson that responded to my frequent apprehensiveness that the produced documentation would not respond to the real needs of the users it is produced for.

Very often, we start writing the documentation being a “blank page”, completely unaware of the domain and the application. And that’s when we first start hesitating whether we would be able to grasp enough information needed to make the experience of the users with the application more pleasant. We dig the technical and the domain details very deep and stop realizing that we already know too much to write the documentation that the real-life users with the real-life problems need. We forget those first “silly” questions that we once had at the beginning, and everything seems so clear to us, that we start producing the documentation that is either too hard to understand or contains too much techy details and almost no information for beginners.

Are there any tips to avoid the “curse of knowledge”? In his article, Tom Johnson shares some great recommendations:

  • Take advantage of your product ignorance.
  • Capture all the questions that you have while making familiar with the product.
  • Refine the “dumb questions” really carefully, as further they may come in handy when structuring the documentation.

It seems, this article caught not only my attention. In his blog, Mark Baker also discusses Toms’ article and an important idea he adds is that product ignorance does not equal domain ignorance. We need to be aware of the domain as much as we can since we write the documentation for the users who are experts in this domain.

Mark adds a couple of ideas to Tom’s article, and I cannot help but agree with them:

  • Domain awareness should mean knowing the whole context – not just separate subject matters.
  • Domain awareness may help us understand the typical users’ pains with our product.
  • Domain awareness helps us write quality and understandable documentation that explains and teaches.
  • Domain awareness is a long and hard path for a Technical Writer, but still a rewarding one.

With this being said, I would also add that analyzing the users you write for (their daily routine, tasks, and troubles) is also one of crucial things to produce effective documentation, which in no way can be omitted or left out.


Docs+Support = AWESOME

Great Write the Docs talk Two Great Teams: Bridging the Gap Between Documentation and Customer Support by Neal Kaplan can help you discover docs-support teams potential.

Highlights of the talk:

  • Support team may help you build the culture of information sharing.
  • Why should you be curious about support cases/tickets:
    • “how to do something…” cases are practically yours.
    • learn about customers experience and expertize.
    • learn the language customers are using.

I myself collaborate closely with the support team on my project, and can totally testify that support team is none less than SME of your SMEs.

Enjoy the talk!

Yana Halaburka, Information Developer at ELEKS

Customers and Content

At the recent Write the Docs conference in Portland, I stood up on stage in front of 400 people and talked about why it’s important to work closely with your customer support team, and the benefits of doing so (besides getting to know your coworkers, of course!).

View original post 30 more words