Technical Documentation Best Practices Series
The Technical Documentation Best Practices Series is a compilation of hands-on books that encompass the whole process of creating user manuals, online help systems, screencasts, plus other forms of user assistance and technical communication.
Each book of the series covers one specific task in the process so that people who are involved in only one phase of a technical documentation project can easily focus on just that part.
The books in the series strictly avoid all sorts of lengthy theory but provide best practices, hands-on solutions, clear recommendations, working aids, and examples that you can easily remember and readily apply to your own work.
Achtelig, Marc Approx. 170 pages; ISBN 978-3-943860-12-2
Even the best information is worthless if users can’t find it. Providing user-friendly structure and navigation is just as important as providing well-written content. However, 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 also wrong. This book tells you how to structure, index, and link your documents so that readers actually find the information they need.
Topics covered: ▪General structuring principles that all structural decisions have in common. ▪Choosing media: Should you provide a printed or printable user manual (PDF), online help, or both? What information should go into the user manual, and what information should go into online help? Which help format should you use? Can context-sensitive help calls be implemented? Should you provide interactive features? ▪Planning documents: Should you put all information into one document, or should you supply several user manuals for specific purposes and user groups? How should you name your documents? ▪Planning document sections: What are the major sections that your documents should consist of? Are there any standard sections that you mustn’t forget? ▪Planning topics: What types of information do your clients need? How should you build and name the individual topics within the document? ▪Planning the order of sections and topics: How should you organize the sections and topics within your documents? What comes first? What comes later? ▪Planning navigation: Which navigational devices should you provide in printed documents and in online help systems? Where should you provide links or cross-references and where not?
|
Achtelig, Marc Approx. 230 pages; ISBN 978-3-943860-13-9
Aesthetics isn’t the only thing that you should be striving for when desiging a user manual template or the style sheet of an online help system. When creating technical documentation, usability, readability, and simplicity are at least just as crucial. The design should please the eye, but at the same time it must communicate the content clearly. In addition, paragraph styles and character styles should be efficient to use for the author when writing the document. The layout process should be automated as much as possible. Because most user assistance documents are frequently updated during theit life cycle, an automated layout process is much more important here than with other kinds of literature. Setting up templates and style sheets that are efficient to use when creating and updating user assistance requires a lot of experience in technical writing. The rules presented in this book are the essence of this experience. All chapters provide various examples that you can use for inspiration and as starting points for your own designs.
Topics covered: ▪Layout basics ▪Setting the type area ▪Choosing fonts and spacing ▪Creating semantic styles ▪Organizing styles hierarchically ▪Recommended screen layouts ▪Recommended page layouts ▪Recommended table designs ▪Recommended paragraph styles ▪Recommended character styles
|
Achtelig, Marc Approx. 350 pages; ISBN 978-3-943860-14-6
Users want manuals that are easy to read, with short sentences, simple words, and unambiguous instructions. Unfortunately, writing plain language is much more difficult than writing overblown instructions that only an expert can understand. Writing complex texts is simple—writing simple texts is complex. This book shows you how to write simple user assistance rather than complex user annoyance. As it’s a book about stating your message clearly, it also states its own messages clearly. It’s free of boring theory and free of highbrow grammar terms, but gives you clear recommendations and catchy examples that you can easily remember and apply to your own work.
Topics covered: ▪General technical writing principles that make your texts plain, simple, and easy to understand. ▪On the topic level: Rules for writing “Concept topics,” “Task topics,” and “Reference topics.” ▪On the paragraph level: Rules for writing the standard elements that form a topic, such as headings, subheadings, procedures, lists, tables, warnings, notes, tips, examples, cross-references, and links. ▪On the sentence level: Rules for building plain and unambiguous sentences. ▪On the word level: Recommendations for using simple words. ▪Spelling and punctuation FAQ. ▪Grammar and word choice FAQ. ▪Standard terms and phrases.
|
Achtelig, Marc Approx. 340 pages; ISBN 978-3-943860-10-8
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. However, there are also cases in which pictures are too complicated and videos are too slow in conveying information. For effective technical communication, images and videos need to be used exactly where they are most efficient, and they need to be designed to clearly convey their particular message. This book shows you the principles of creating effective visuals.
Topics covered: ▪Choosing the right medium and place: What works best in a particular case: Text? Images? Animations? Videos? Interactive components? How many images should you include, and where should you put them? ▪Common basics of visualization: General design principles that apply to both creating images and creating videos. ▪Images in general: Fundamental tips for creating effective images, no matter what these images show. ▪Images of hardware: Particular tips for creating drawings and photos that show physical devices. ▪Images of software: Particular tips for creating screenshots and other images of software. ▪Video design: Tips for creating effective instructional videos, as well as solutions for embedding these videos into technical documentation. ▪Video production: Tips on how to organize the creation of instructional videos and on the underlying technologies. ▪Interactive content: Ideas for implementing interactive components, such as interactive 2D and 3D images, hypervideos, and augmented reality applications.
Like all the books of the Technical Documentation Best Practices Series, the book focuses on practical tips and examples that are easy to implement in real projects. In case you don’t create your visuals yourself but instead assign this task to a graphic designer or to an agency, the book makes you a competent client and gives you the expertise to review the results critically.
|
