Technical Documentation Solutions Series
The Technical Documentation Solutions 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.
Readers of the series are:
▪full-time technical writers
▪developers, marketing professionals, and product managers who occasionally write some technical documentation
▪designers who create templates for user manuals and online help systems
▪multimedia experts who create screencasts, tutorials, and e-learning courses
Approx. 366 pages; ISBN 978-3-943860-08-5
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 and gives you clear recommendations and catchy examples that you can easily remember and apply to your own work. It’s technical writing made easy—both for the author and for the reader.
▪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.
Approx. 188 pages; ISBN 978-3-943860-04-7
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 that your documents contain.
Drafting the structure at an early stage saves you a lot of time and money. As long as you’re still working on a plan, you can revise initial decisions quickly and at no cost. However, if you’ve started writing without a plan and let the document “evolve,” restructuring or even rewriting an existing document can be time-consuming and costly.
▪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 and social 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 shouldn’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?
Approx. 242 pages; ISBN 978-3-943860-06-1
Aesthetics isn’t the only thing that you should be striving for when you design a template. When creating technical documentation, such as user manuals and online help systems, usability, readability, and simplicity are just as crucial.
The design must please the eye and at the same time communicate the content clearly. Paragraph styles and character styles should be efficient to use when writing the document. The layout process should be automated as much as possible. As user assistance documents are frequently updated, an automated layout process is much more important here than in other kinds of books. For example, when you insert a new paragraph into a document, this shouldn’t result in you having to manually tweak all subsequent page breaks—not to mention page numbers, cross-references, the table of contents, and the index.
Setting up templates and style sheets that are efficient to use when creating and updating a document 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.
The book is both for designers who are in charge of creating a template for a user manual or online help system and for authors who have to create their own designs and style sheets. It provides clear rules and unambiguous recommendations. No boring theory, no musings, no shoptalk.
▪Setting the type area
▪Choosing fonts and spacing
▪Avoiding manual formatting
▪Creating semantic styles
▪Organizing styles hierarchically
▪Recommended screen layouts
▪Recommended page layouts
▪Recommended table designs
▪Recommended paragraph styles
▪Recommended character styles
Coming soon; ISBN 978-3-943860-10-8
If you want to be notified when this book is available, please . Thank you.