by Race Bannon on April 8, 2011
Kurt Ament authored a book titled Single Sourcing: Building Modular Documentation in which he clearly explains how technical communicators can develop standalone, topic-based information modules that act as the building blocks for a robust set of documentation based on the individual building blocks. This is currently a very popular approach to technical documentation and much has been written about this approach by others since the publishing of Ament’s book.
I’m big on basics. I like breaking things down to the most elemental ideas or concepts in order to fully understand the details that surround them. When it comes to modular (topic-based) documentation, here are what appear to be the three key concepts:
- Separate (chunk) information into standalone topics. Most technical communicators who follow this process use three common content types: concept, task and reference. The goal is to create chunks of information that separately contain descriptive information (concepts), task-oriented information (tasks), and reference material the user can look to for more detailed or related information.
- Use topic titles that clearly represent the topic’s contents. No two titles should be the same in order to ensure no confusion. These highly descriptive titles should be easily “scannable” so they can act as visual cues to direct users to the specific information they need with minimal hunting around the documentation. Unique and descriptive titles also facilitate better searching.
- Link it all together in logical ways. Link related topics together in a way that allows the user to easily jump around the topics with little need to perform further searches.
There is a lot more to creating modular documentation, but if you understand these three basic ideas, the rest of the details will fall into place easily.
For more information, visit these sites:
Editing Modular Documentation: Some Best Practices
Challenges and Advantages of Modular Documentation
Modular Documentation: Bringing the Pieces Together
by Race Bannon on April 5, 2011
Since my friends, acquaintances and colleagues all know I’m a writer, I’m often asked how they can best improve their writing. While there is an endless collection of tips and tricks one can employ to become a better writer, there is really no replacement for practice. Writers write. The more you write, the better you get.
Finding the motivation to write however can be a challenge for some. If writing is not a part of one’s daily business or personal life, a suitable carrot must be dangled in front of someone to motivate them to write. Some suggest the use of a personal journal and I think that’s great. My only issue with using journals as writing practice is that it’s not outward facing writing. In other words, journals are only meant to be read by the writer and thus sloppy writing will be tolerated. You need writing that is meant for the eyes of others.
I suggest thank you letters as one great learning mechanism. Here’s why.
Writing thank you letters to those people in your life you wish to thank fosters gratitude, makes the recipient feel good, and at the same time offers you a means to practice and improve your writing because you want the letters to be clear and beautifully written. It’s a positive all around and thus can properly motivate you to practice writing.
You might even go so far as to make writing thank you letters a daily, or at least regular, practice. John Kralik did this when he undertook the task of writing a thank you letter to someone in his life every day for a year. Kralik documents his thank you letter journey in his book 365 Thank Yous: The Year a Simple Act of Daily Gratitude Changed My Life which has garnered significant praise.
So, who in your life do you want to thank? Start writing that thank you letter now.
by Race Bannon on April 3, 2011
The ability to communicate is a fundamental skill everyone must master. Both our professional and personal lives improve anytime we increase the effectiveness of our communications. This blog is my attempt to share with you my efforts to improve my communication skills in the hopes that you will find such sharing useful.
Contemporary communications occur in a multitude of ways – the written word in all of its forms, the spoken word in all of its forms, and the various visual mediums (graphics, photography, videography, and so on). Taken together, they form the foundation skill set that separates effective and successful people from those less skilled. Such skills are absolutely vital to our personal and professional success.
Since I’ve had significant success as an effective communicator, perhaps sharing my own knowledge and experience will be of help. But I do not consider myself the ultimate expert and wherever I find wisdom or insight into how best to communicate with our fellow human beings, I’ll be adding that information here as well. Whether it’s the construction of a simple email, the drafting of a complex document, the delivery of a speech, or the best way to visually convey your message, I intend to touch upon any and all aspects of how to best communicate.
Thank you for visiting and I hope you return often.