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!
“At the end of the day, don’t just sit back and think, what great documentation I’ve created. Instead, keep the focus on the real end game: product adoption.” Sounds like a message provoking self-analysis and lookback at all of the work you have done so far 😊
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.
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?
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.
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.