Technical Documentation Best Practices Knowledge Base

The Technical Documentation Best Practices Knowledge Base is an electronic guide for authors of technical documentation. With just a few clicks, it provides the expertise needed to create high-quality user manuals and online help.

The Knowledge Base is available online anytime and anywhere. It always contains the latest contents of all my books, concepts, and other working aids. In addition, the Knowledge Base also contains some information and tools that have not yet been published as a book – always up to date.

Why use it?

With just a few clicks, the Knowledge Base provides you with the best practices you need to create high-quality user documentation.

The Knowledge Base doesn’t provide lengthy theoretical elaborations but gives practical recommendations that you can easily remember and use for your own work.

You don’t need to be a linguist to understand the technical writing rules, and you don’t need to be a designer to implement the design guidelines. All recommendations come with catchy examples.

The Knowledge Base 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 Knowledge Base if you write in languages other than English.

Who should use it?

The Knowledge Base was developed for anyone involved in the creation of technical documentation, whether from the fields of

• technical writing
• development
• training
• product management

The Knowledge Base provides a ready-to-use, standardized, and continuously updated editorial guide for your entire team. Without any effort involved in creating this guide yourself. At unbeatable costs compared to developing an editorial guide on your own.

Contents

The Knowledge Base covers all essential topics related to the creation of technical documentation:

Rules on structuring

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 Knowledge Base 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 didactic order
• makes it easy for users to find the needed information
• separates what’s important from what’s less important

Rules on designing

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 system. 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 Knowledge Base 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 Knowledge Base 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.

Rules on writing

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 Knowledge Base provides you with proven technical writing rules and practical tips that will help you to create content that’s:

• well-structured
• clearly written
• easy to understand
• actually helpful

Rules on visualizing

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 Knowledge Base 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
• video design
• video production
• interactive content

Screenshots

Expandable texts as well as a global search function and a global index guide you quickly to the relevant content with just a few clicks.

Sample topics (click on any image to enlarge):

Global alphabetical index:

Global search function:

System requirements

All you need is a computer or tablet with an up-to-date browser and access to the Internet.

Pricing and order

The price depends on the number of users plus optional customization. Please contact me for a quote.

See also my other technical documentation work aids.

Or read on with: Technical Documentation Template