Liz Fraley began the last day of LavaCon 2019 talking about style guides. Style guides are to create consistent experiences for end-users, no matter where the content is delivered or who wrote it. Also, style guides are an offloaded effort, institutional memory, and good for onboarding. Documentation on how we write our content. If something is never written down, it does not get reported.
How you write tells people what community you belong to.
Style guides are references for writing style. Included writing practices, writing usage, terminology, and voice/tone. Your corporate voice. Include guidelines that are unique to you, that fit your context. List company/product specific issues, such as proper/improper use of your product names.
Not only do you need to include rules, but include examples. And not only good examples, but bad examples. With both, it makes the rules easier to interpret.
If you have teams contributing content in different languages, then it's good to have the style guide in those languages.
Formatting style guides describe the official look and feel of your output. Defines the implementation of your templates, CSS, XML transforms, and more. A format style guide is a specification.
In XML environments, there's another style guide: XML style. What tags to use and their context. Here it's extra-important to have examples. And if you're a DITA shop, you want to add your DITA rules.
No comments:
Post a Comment