Technical Writers’ Companion – Purpose and Features
The Technical Writers’ Companion is an electronic guide, knowledge base and reference for technical writers and authors of technical documentation. It provides you with the expertise needed to create high-quality user manuals and online help systems.
Powerful authoring tools produce nice-looking manuals and help systems. However, the authoring tools don’t help you to structure, write, and visualize your content.
This is where the Technical Writers’ Companion comes in. As an electronic guide, knowledge base and reference, it provides authors of technical documentation with the best practices to create high-quality user manuals and online help systems.
The Companion has been designed for all people who are involved in creating technical documentation and user assistance:
▪Are you a developer or marketing professional? Do you need to create some user assistance for a product that you’ve developed? Do you want to create a manual or online help system that’s more than just a placeholder—help that actually helps and guarantees a positive user experience?
▪Are you a technical writer? Do you need a professional knowledge base and technical writing style guide at your fingertips? Are you tired of having to compile this information yourself from various sources?
▪Are you a team of developers, marketing professionals, or technical writers? Do you need to achieve and maintain a consistent quality standard throughout all of your documents?
If so, the Technical Writers’ Companion can help you.
To learn more about the Companion, you can .
The Companion doesn’t provide lengthy theoretical elaborations but gives practical recommendations that you can easily remember and use for your own work.
You don’t have to be a designer to implement the design recommendations, and you don’t have to be a linguist to understand the technical writing rules. All recommendations come with catchy examples.
The Companion is written in plain, simple English that you can easily understand even if you speak English only as a second language. Almost all rules are universal, so you can even use the Companion if you write in languages other than English.
Structuring user assistance isn’t as simple and obvious as it may seem:
▪If you think that your document structure should follow the structure of your product’s components and functions: You’re wrong.
▪If you think that the type of document that you prefer is the same type of document that your clients prefer: You’re wrong.
▪If you think that all the information that you have is important: You’re wrong.
The Companion provides you with effective rules and tips that help you find a structure that:
▪reflects the users’ mental model
▪presents the information in the best didactical order
▪makes it easy for users to find the needed information
▪separates what’s important from what’s less important
You never get a second chance to make a first impression. Aesthetic design can’t compensate for poor content; nonetheless, it’s a key factor of effective technical communication. An attractively designed document motivates users to read it much more than an amateurish-looking manual or help file. What’s more, a clear design and a well-thought-out template also motivate and help you, the author, to produce content that’s just as clear and user-friendly.
The Companion summarizes the basic design principles that you should follow and provides practical examples as starting points for your own modifications.
Aesthetics, however, isn’t the only thing that you should be striving for when you design a template. Usability, readability, and simplicity are just as crucial. Defining paragraph styles and character styles that are efficient to use for the authors who write and update a document requires a lot of experience in technical writing. The rules given in the Companion are the essence of this experience. They can prevent you from making the same mistakes that have cost other authors lots of time and trouble.
Everyone can write, but not everyone can write so that everyone understands.
▪If you’ve explained something thoroughly, this doesn’t mean that your information is useful.
▪If you’ve explained something accurately, this doesn’t mean that you’ve explained it adequately.
▪If your sentences are grammatically correct, this doesn’t mean that readers understand what you want to say.
The Companion provides you with proven technical writing rules and practical tips that will help you to create content that’s:
▪easy to understand
Words are not always the best medium for communicating technical information. Sometimes, a picture, a simple animation, or a short video can intuitively show within a few seconds what words can hardly describe.
The Companion provides you with proven best practices for creating effective visuals. This includes:
▪Choosing the right medium and place
▪Common basics of visualization
▪Images in general
▪Images of hardware
▪Images of software