Using Style Guides to Achieve Content Collaboration and Consistency

Slide 1: Title Slide

Hello! I'm Liz Fraley. Welcome to my virtual session on Style Guides. Styles Guides are a great topic and I love to talk about them. I first gave this presentation at STC Summit in 2019. I had standing room only and people out in the hall. Since then, I've given it at Lavacon and in the TC Dojo and several other places. Normally, I like interacting with an audience and hearing about their experiences. So, if you are so inspired, send me your comments, your stories, or whatever comes to mind. And, in the future, It’ll be a better session for all of us. Thank you.

Slide 2: About Liz Fraley

Again, I’m Liz Fraley. And the main thing I think you should know about me is that I love creating connections with people and sharing knowledge. I have a BS in Computer Science, and an MA and BA in English. I read over 200 books, thousands of articles, blogs, news, and mailing lists, every year.  I sit on the boards of and volunteer for 3 non-profits, one of which I started.  I'm always searching for new ways to increase the knowledge of the professionals in the communities I serve. For me, it's all about empowerment. I may not know the answer, but I always know where to get it -- or at least how to find it. Think of me like the librarian behind the research desk at the library. Presentations like this are my way of bringing people together to share knowledge, ask questions, and enable each other. The link in the lower left hand corner http://bit.ly/summit19-style is the public event page for this presentation. These slides are on that page as are a growing list of resources about style guides.  We know that you want to learn and so do we. So be sure to visit that page. While this video won't change, that page will always be current.

Slide 2: Who We Are

For those of you who don’t know us, we are Arbortext specialists from California. We have been a part of the PTC channel program for over 15 years and we have always focused on Arbortext. Our experience goes back even farther since we were implementers and users of the arbortext products long before. We are pretty passionate about the suite and what it can do for our customers. We have seen it first hand with some amazing transformations for tech pub groups after adopting Arbortext and best practices and we have lived it as well.  We have even written a few books to help others gain knowledge and confidence

Slide 4: What Comes To Mind...

What comes to mind when I say Style Guide? Some of the more common answers I get from techcomm folks are rules, controlled vocabulary, formatting, corporate branding, writing guidelines, voice and tone. All very good answers.

Slide 5: What's a Style Guide For?

Here's what my answer is: It's a consistent experience for end users no matter who creates the content or how it's delivered. It is the guidelines and rules that provide the consistent experience.

Slide 6: What's a Style Guide For? (bottom)

But it does other things too. It offloads effort so you don't have to keep everything in your head. It adds institutional memory which is the history of whys, hows, and the decisions that were made to aid with staff turnover. It can also help with onboarding so that the new people can come up to speed without asking a million questions and become productive a lot quicker.

Slide 7: Most Common Reaction

However, if you ask this question to the other people - the general public, the most common answer I get is a reference document for formatting. And in particular it's the formatting of research, reference lists, and citations. Do you use the APA format or the MLA format or the Chicago Style? It's not surprising to get this answer because we've been trained through all of our years at school. We want the rest of our community to accept our work and recognize the research we've done.

Slide 8: The Type Decides the Format 

Let's talk about what that means: Fundamentally it's that the type defines the format.

If you're writing a citation for one author, it's different than if you're writing one for three authors, or an unknown author, or an author and a translator. Or multiple works by the same author, in the same year or different years. There are formats for letters to the editor, for periodicals, for film reviews, for blog entries and songs and podcasts and other online sources. Each one of these, depending on what you're citing, is formatted in a specific way. And, in addition, which format you use marks *you* as being a member of a particular group.

Slide 9: Example: Blog Citations

For example, MLA looks slightly different than the APA and both look different from the CMOS (Chicago style). These examples come from the Citation Style Chart at Purdue University's Online WRiting Lab and it's a fascinating resource to read through. It gives you examples of all the possible cases and the differences between them. The MLA style puts more emphasis on the author - showing both the first and last name. The APA style has less interest in the author and more interest in the time frame and what's being documented. Hence the initial for the author's first name and more information on the date and when it was retrieved and the context it came from. Which format you choose identifies you as coming from a background of MLA or APA.

Slide 10: Comparing MLA, APA, and CMOS

If you want to compare them, you can dig into the Citation Style Chart for more information about the different styles. And it talks about how the MLA places more emphasis on authorship because it's part of the humanities. Where the APA is talking about social sciences. It's emphasis on the date and when the work was created have higher significance. They also care more about whether it was a recording or a physical text. It's a different perspective and the format reflects that. Chicago Manual, on the other hand, is more about the bibliography and the author-date system. It places more emphasis on source origins. Footnotes, endnotes, and where information comes from. Rather than who wrote it or when it was written.

Slide 11: What else do these guides cover?

In addition to references and how citations are constructed , these style guides also cover a few other things like:

• They talk about primary source methods: How to do interviews, how to make observations, and then how to document that. How to do primary source research.
• They also talk about how to do secondary source research from books or journals or the internet.
• And they include practical advice about evaluating research sources, how to quote or paraphrase so as to avoid plagiarism. How to write with statistics, avoid bias and write abstracts.
• Abstracts are significant to us as technical writers---DITA has the focus on Short Descriptions and Titles and the ideas are similar.
• How you format citations and how you format documents are also found here. We talked about citations, but they also include advice for differentiating headings, working with seriation rules, tables, and figures
• More recent editions have started to include advice about strategies for fair use, something that we all face if we're including references to popular culture or memes or gifs from some other source. YOu need to know how you can use that without getting into trouble.

If that's the first most common answer, what's the second one?

Slide 12: Second most common

Most commonly, the answer I get is that it's a writing style guide. A reference for writing style. How you write. The Chicago Manual also includes this guidance, but so does the MS Manual of Style and Strunk & White. These should all be familiar to all of us.

Slide 13: Writing style guide

Writing Style Guides are about writing practices. They are guidelines for usage -- of terminology, of grammar, of capitalization, of spelling. It also includes guidance for voice, spelling out how corporate voice should be characterized. That includes things like word choice and tone. Passive voices vs active voice and do you write in first, second or third person? How should content be written? And How do you address the reader? What approach do you take? What is the personality of the corporate writer? It may also include how you're going to use Simplified Technical English or if you're going to use it at all. Or, which parts you're going to use.

Slide 14: Include guidelines that are unique to you

You want to make sure that any style guide at this level -- the writing style guide -- includes guidelines that are unique to you, your products, your company, your content, and your customer. It's not enough to simply point to the Chicago Manual of Style. You have to make sense of it in your own context. You want to provide guidelines that directly reference your customers, your company, your content, your situation. For example, rather than just pointing to the chicago manual of style, use it as a model that you extend in your own style guide. You can list specifics for your situation and refer back to Chicago to settle disputes that are more generally applicable and that are not specifically called out in your corporate style guide. Chicago becomes the fallback for rules not otherwise specified. You don't have to reproduce it, but you should extend it to cover your own situation. You want to include company and product specific issues. What is proper use of the company and product names? What is improper? Can the company name or the product name be used as a possessive? This is not as obvious as it would seem. Legal always has something to say here. What about copyrights and trademarks? How can they be used? Are they nouns? Adjectives? Can *they* be used as possessives? These are all things you need to specify in your writing style guide.

Slide 15: Some places to start

Here are some places to start. If you're ready to extend and start creating your own writing style guide, you want to include things like 

• Punctuation, abbreviations, common practices for field definitions used all across your product, you want to promote consistency (in description and presentation) and include guidelines for length, format, decimal precision, etc).
• Establish standards for terms:
  • Is it "hit" "click" or "click on"
  • Is it "select" an "clear" or "check" and "uncheck"
  • You want to make sure everyone uses the same words consistently for comprehension and clarity to your customers
• What about emphasis? In this case, it's not just usage, but *overuse* what part do they play in assigning significance in the text? For what and how should emphasis be used?
• Images are another good inclusion - what format, resolution. How do you create callouts and reference them? There are ways to do callouts that result in content that is more or less amenable to translation, making this a critical inclusion if you're localizing your content. Either way, you want a standard way to handle images so they are all presented consistently.
• Error messages, code examples, capitalization, pronoun usage, verb tense..all of these are places to start and should be included in your writing style guide.

Slide 16: Include Examples

An extremely important part of any style guide is the inclusion of examples. They are almost more important than the rules. It is easier to understand and interpret an example than to read and interpret a description. In fact, it is even easier to interpret when you have both a good and bad example. Having both an incorrect and correct example as well as the guideline can give you a way to make the rule meaningful to someone who is reading the style guide and trying to figure out what to do.

For example, this one says:

"Spell out United States with possible. If abbreviation is necessary, use "U.S." not US, USA, or U.S.A. and don't spell it out on the first mention."

We've got a fairly comprehensive rule and a decisive answer that refers to a fairly common rule regarding acronyms. 

This example is from Cathy Jones @ Jack Henry who did a TC Dojo webinar in 2018 and the rule reflects their business, their knowledge of their customer, and the position they want to take in their documentation. They spell it out in their corporate style guide so they don't have to waste time and money and resources tracking down all the different ways this could go.

First is a problematic concept anyway - especially if your content is on the web. Where exactly is first? How did the user get here? They are not reading front to back...

Give a bad example. Give a good example. And describe the guideline as well.

Slide 17: Other things you can include

There are other things you can include at this level - like the use of gender-neutral language. How are you going to use it? Are you going to use it? What are the guidelines for doing so? Who is the audience you're writing for?  A good description of the audience at this level will help make sure the rest of these rules are easily understood. When to use gerund phrases, hyphens, en or em dashes.

The last one has become more important because it's becoming more of an issue: How do you handle sensitive customer information in images? Sometimes you can see through things that are just blacked out in a PDF or if you hand a word document around that had change tracking in its history. A few rules about making screenshots and help your team do things in the best possible way to preserve customer information.

That's two. What's the third most common type of Style Guide?

Slide 18: 3rd: A Format Specification

Typically, it's a format specification for layout and the design of the official look and feel for output. This is often a FrameMaker template or a Word template or your CSS and stylesheets. This is a popular answer as well. This is paragraph styles, character styles. It's look and feel.

Slide 19: A Format Style Guide is a specification

I want you to think of a Format Style Guide as more of a specification. This document is the detailed standard for look and feel for any deliverable type. It should cover format-specific decisions that are not in the Writing style guide. Include as much specific information as you can, so the implementer -- the stylesheet or template designer, can implement the desired look and feel. Every style guide should always be a living document continuing to evolve and reflect current practices. It needs to be updated whenever there are style changes. 

Although it may seem as though I'm talking more about printed documents, this is not entirely true. Even web pages have layout design specifications. I'm talking about that design specification. This is the documentation about what is implemented in the CSS. I can guarantee that if you think a css is self documenting, you've never had to go debug someone else's. You won't remember what you did next year when Marketing comes to you ready for a whole new look and feel, never mind trying to remember it next week. None of what I'm talking about is deliverable specific. Document your format design decisions for all your deliverables. You'll thank me later. That's what this level style guide is for.

Slide 20: What these include

Here are some places to start with this level specification:

• Official colors, fonts and typefaces. 
• For print, what size pages are you producing and how do you handle blank pages: Do you say "this page intentionally left blank" or do you just leave it blank?
• For web, you want to know how to break up pages, especially if you're generating multiple pages. There may be times when you don't want things to break in a particular way and cases when you do. What are those cases and can you lay that out?
• What about Tables of Contents and Nav bars? Are there limitations or inclusion/exclusion rules? Do you include header or just down to a certain level? Does that change for different delivery types?
• How do you handle generated text "Contents or Table of Contents? Which should authors use? No one should ever have to type that, it should be generated by whatever is governing format generation.
• Similarly, how are links constructed? Do you put the title of the target page? The URL? What goes there? Do you also include a "Go to" or "see.."?  

Anything that's generated needs to be specified at this level. As does anything that is unique to a specific deliverable type and that is part of the automatic formatting. These are the things that are PDF only and the things that are HTML only and the differences between them so your implementers know where to fix things and where to find them. This can include indents, numbering schemes, other spacing issues. This is your specification.

Slide 21: Example

Here's a print example. I will typically lay it out on graph paper and measure specifically and get layout coordinates. I want to know exactly where things fall on the page so that when I'm implementing, all I have to do is execute. And just like the other guides: Include an example that has both the representation (the example of what you're aiming for) and the description of the guideline in words.

The equivalent of this for web is wireframes. Designers do very similar things for web design to lay out how it's supposed to look and where things should fall on the page, including how it changes when you switch viewports and dimensions. All of that needs to be documented.

Slide 22: Example: Headings (APA)

Here again we have examples. A good style guide includes both the description of that design and an example of the design, so you know what you're aiming for. Think of this level style guide as a spec because that's what it is.

If that's three. What's the last type of style guide?

Slide 23: In XML environments, we find a fourth kind of style guide

This one doesn't always get the attention it deserves. Most of us take it for granted that we can use someone else's guidelines to do all the heavy lifting. But like the second-level style guide, you can use someone else's guidelines as a foundation that you extend and apply  to your own content

I call this level the Tagging Style Guide. Some people call it an Authoring Style Guide. You might hear Information model or a DITA style guide, if they're talking specifically about DITA. You really only find these when you have XML authoring and not simply Desktop Publishing.

Slide 24: The tags to use and their context

Here's what goes in this type of style guide: XML content models are large and you might not be using every tag available. You should document which tags you are using and what purpose does that tag serve in your content set? You will want to make it relatable to the doctypes original purpose for that tag. Consult the doctype specification to understand the tags and their purpose and decide how that applies to your content.

We had a medical device customer who built surgical implements with various hand tools that can be attached and swapped out. We decided that was user-interface because that hand tool is the interface being used to interact with the machine. They decided to use the UI CONTROL tag to mark it up in running text.

Again, as always, Examples! Examples! Examples! What are your nesting rules? DO lists go in the paragraph or are they siblings? Do you allow nested topics or should all topics be separate and joined through a map construct? What about tables? There is more than one type available to you. Which one gets used under what conditions? You might also want to talk about key structures, naming conventions, profiles and filtering... All these are suitable for inclusion in this level style guide because they can have ripple effects in downstream processing. 

If you don't get it right in the markup, then you can guarantee that the downstream transformation will not come out right. And likewise, if you add a new profile, you need to know how it intersects with the others and which content is affected and that any content currently under differentiation with the old profiles gets the new one added to it (or adjusted to accommodate it).

Document all of it and what each thing means. All of the decisions that went into content construction and processing and the whys should also be included here because you'll never remember and, if you win the lottery and move to fiji, someone can take over for you without missing a step. This is that institutional memory we talked about before.

You can also include some of these other things, if you haven't already addressed them in another level style guide. Tags and attribute values that trigger actions in processing -- like landscape page orientation (are you rotating text on the portrait page or are you actually rotating the page to landscape orientation?) 

Slide 25: Doctype-specific writing guidelines

Every group writing documentation finds specific information patterns that develop in their content.  Likewise, do you have a task with substeps or do you want to join sets of tasks with a map construct? So they get grouped together? What are your information patterns and how do you implement them? It matters so you can guarantee consistent presentation of information to your users. You're effectively training them in what to expect and how to interact with your content.

Slide 26: Additional guidelines for DITA

If you're working with DITA then you know that one topic answers one question well. As a team you have to decide how to ues the DITA content model with respect to your content. What topic type should be used for any particular piece of content?

For example:  

• The product overview -- do you all agree that it's a concept or should it be a reference? What is the guiding principle for deciding which topic type to use?
• Maps. Are these only for deliverables? Or can they be used for packaging of smaller content units?
• What are your reuse strategies? Do you use warehouse topics? Do you use conrefs or conkeyrefs? And at what level do you use them ? And when do you use one over the other?

For a more complex example at a completely different level, say you are creating on-product help and all that the software development team will give you is a single landing page. You have to figure out how to construct this page as a jumping off point while still making it relevant and complete for expert users. And the pattern you establish will be used again and again.

All of that goes in this level style guide and like the others, this is a living  document.

Slide 27: Example: Short Description

Here's an example. I got this from DITA Best Practices. The guideline has a description, but it also has the title, which is necessary to evaluate the effectiveness of the short description. Then it shows a good and bad example to demonstrate. Writers can look at this and understand whether they're doing things the way they should be done. By having both good and bad examples, you can learn through comparison and identify how to improve a bad one and turn it into a great one. The book is full of these example and it's a great resource to have at your disposal.

Slide 28: That's a lot of style guides

That's a lot of style guides.  I've shown you four and we haven't even talked about process. 

Here's what you should remember:

• External style guides are group-specific and cover basic situations.
• You want to extend those guides to cover your specific writing style,
• You want to add specifications to cover your formatting
• And you want to add tagging guides for your xml environment, especially if you're using DITA

That's four things to do, it's a lot. They can become big, messy and unwieldy but there are things you can do to mitigate the overhead..

Slide 29: Some parting advice...

Start small and hit the immediate needs first. Get the low hanging fruit that gives you the biggest immediate improvement in the content that is high touch or that writers are frequently changing. Don't be overly comprehensive, I know that some of us tend to be packratty. If it gets too big no one will use it. You can break it up, you can create templates, it doesn't all have to be in one big document. I know that Arbortext has all kinds of features that can instantiate style guidelines without a lot of overhead and that fall inline with author work processes, simply to improve their lives. Other tools likely have things as well. Make use of whatever you have. Turn it into an online website with search and a TOC. That can help make your style guide more accessible and useful. WE've all been trained to search, so this can be a really good option and improvement over a big PDF.

Think of your style guide like it's just another deliverable and treat it accordingly. In this case the customer is you and your team. Giving it the respect it deserves will increase  your success and improve usage. Use that same professionalism to write your style guide as you would any other deliverable.

The last bit of advice I'll share is to establish a governance board. There are multiple benefits for doing so. First, you can rotate who participates and make sure everyone on the team has a chance to be involved. Involvement increases acceptance. You're all working together. Plus, different eyes see different things. Your style guide will be better when you have more contributors coming together. It is OK to have a single owner for the guide. A single person can help facilitate disagreements, making final rulings, and be a recognizable voice for communicating changes. You might rotate this position so everyone understands the responsibilities associated with the role. It's far easier to be tolerant of someone else when you've been in their shoes.

Slide 30: Resources #1

Here are some resources. The slides are on the website as are the links to the TC Dojo webinars on style guides by Keith Schengili-Roberts and Cathy Jones. A lot of companies have published their style guides online and it can be interesting to see how they differ and compare.

Slide 31: Resources #2

The Amazon Product Page style guide isn't for amazon's help writers, they're for vendors who are writing product pages for their products. It's interesting to see how they tell people how to write for amazon. 

Slide 32: Resources #3

Lastly, here are the DITA resources we recommend. Two of these are short links because we recommend them so frequently. All are good if you're learning about dita and starting to create your dita style guide.

Slide 33: Closing Slide

Thanks for attending. I'm Liz Fraley. Be sure to connect with me on LinkedIn at http://lizfraley.me

Don't forget to come to the Q&A session! Bring your stories, your experiences or anything else that comes to mind. I'm looking forward to hearing from you.