Authoring tool setup and creation of templates for technical documentation
I design and create templates and style sheets for user manuals, online help, and other forms of technical documentation. I take great care that the templates don’t just look nice, but that they are also user-friendly and efficient for the authors to work with.
Do you need a template or style sheet for a printed user manual or for online technical documentation?
I can create individual templates for you that go well beyond just looking good: They present the information in a user-friendly, clear, and memorable way. A good template is also efficient to use for the author. This can save lots of time and thus money. The savings multiply with each new document and with each update of a document that’s based on the template.
While the visual design of a template could also well be delegated to a graphic artist, defining paragraph styles and character styles in detail requires a lot of experience in technical writing and also the ability to think ahead for future documentation requirements.
Characteristics of an efficient technical documentation template
▪Less is more: Both for the reader and for the writer of technical documentation it is vital to have a clear design that encourages a focus on the content and that doesn’t distract. The key rule is: Less is more. Having a small number of well-thought-out styles is much more practical than having a plethora of individual styles for every exception you can think of.
▪Semantic styles: As another basic principle, styles are never named according to their visual appearance but according to the content of the text they’re to be applied to (so-called semantic styles). Therefore, for example, a style will never be named “ArialBold10Point” but “emphasis” or “menu item” instead.
This constantly forces the author to reflect on the structure of the documentation, and it’s the key requirement for structured authoring, such as authoring with XML DITA. Even if you don’t use these methods today, semantic styles make you ready for the future.
Semantic styles are also essential in case you decide to modify the design. What would you do with a style named “ArialBold10Point” if you decided to change the font?
▪Easy to change: All styles are organized hierarchically. Child styles inherit the properties of their parent styles. Thanks to this approach you can, for example, change the font of all styles within a document with just one click, simply by changing the root style.
▪Easy to assign: All styles are named so that related styles (for example, all styles for lists) are displayed directly one below the other in the styles catalog of your authoring tool.
▪Easy to remember: Keyboard shortcuts are defined for the most frequently used styles. A well-thought-out system ensures that you can easily remember these shortcuts.
▪Automated formatting: A sophisticated definition of certain style properties can save a lot of manual formatting work. Page breaks, for example, can be automated to a large extent simply by defining the appropriate paragraph style settings.
See also my other services.