+1 408 660-3219 sales@single-sourcing.com

How do you establish a style guide, and how do you keep it going? In this session, I’ll talk about my experience implementing and maintaining a corporate style guide. What started as a casual department guide for 25 tech writers is now a formal style guide for all content creators throughout the company, and I’ll share some tips and tricks we learned along the way.

About the Visiting Dojo Expert

Cathy Jones pictureCathy Jones is a Technical Writing Project Manager for Jack Henry & Associates, Inc. She has been with JHA's Enterprise Content Services group for 13 years. She has helped establish a corporate style guide, coordinates editing services for writers throughout the enterprise, and recently served as the project lead for a CCMS implementation. She has a Master's Degree in Technical and Professional Writing from Missouri State University.

Watch the Video

Recorded: 4 June 2018

Transcript (Expand to View)

[00:00:00.480] - Liz Fraley

Good morning and welcome to TC Dojo from Single-Sourcing Solutions. The TC Dojo is a techcomm community that is driven by you. Tell us what you want to learn. You choose the topics and we find the experts. In the TC Dojo open session today, we have Cathy Jones from Jack Henry and Associates, she's been with them for 13 years. During this time she has served as a technical writer, the project lead for CCMS implementation and has coordinated editing services for writers throughout the enterprise. She's also been working on their corporate style guide. She comes to the TC Dojo through one of our attendees. Our ongoing Services Survey asks for topics and presenter suggestions, and Cathy was one of those suggestions specifically for this topic.

[00:00:43.560] - Liz Fraley

We're especially grateful she could come to the TC Dojo today and share her experience with all of us. Cathy wants to save your questions until the end, so be sure to type them in when you think of them. So you don't forget what you wanted to ask.

[00:00:56.370] - Liz Fraley

Cathy, It's all yours.

[00:00:59.360] - Cathy Jones

You should be seeing it now.

[00:01:01.140] - Liz Fraley

Perfect.

[00:01:05.090] - Cathy Jones

All right, well thank you Liz and thanks everyone for joining me today and we are here to talk about style guides, so let's go ahead and get started. All right, just to give you an idea of what I'm going to talk about today, I wanted to start off with some brief background about myself and my company, Jack Henry and Associates, just so you have some context for how we've grown our style guide, I'm going to tell you a little bit about our style guide story, so how we went from not having much of a style guide at all to having a corporate style guide for all content creators throughout the company.

[00:01:40.650] - Cathy Jones

And we did that over the course of about 10 years. And then of course, the main reason we're here, I'll give you some tips and advice that we learned over that 10 year journey and talk about how we decided what to include in the guide and how we've been growing our guide very deliberately over the years.

[00:01:59.190] - Cathy Jones

So first off, about Jack Henry and Associates, or JHA, JHA is a banking software company, we provide platform online, mobile and payment solutions to banks and credit unions, we were established in 1976 and our headquarters are in Monett Missouri. So you can see here that we have over 300 products and services that we provide, we have 9,000 customers and 6,000 associates, and all of that adds up to a lot of content created throughout the enterprise. So we've got documentation, marketing, education groups, all producing customer-facing output not to mention all the internal content that's created throughout the company as well. So with all that content being created, we really had a need for consistency and standards for that content.

[00:02:49.730] - Cathy Jones

So enter me, I've kind of found myself in the role of style guide maintainer for JHA Style Guide and Liz already told you a little bit about me, but to give more detail. I lead our groups editing team, which provides editing services to the entire company, so we edit all documentation that our department produces, as well as content that's submitted by other groups throughout the company. My team also trains all new writers in our department on authoring and style standards, and we maintain the corporate style guide which is of course what we're here to discuss.

[00:03:29.130] - Cathy Jones

So now that you know a little bit more about me and about JHA and the context in which we've built up our style guide, I'd like to tell you more about our guide itself. So where we've been, and where we are today and how we got there. So up to 2005, the JHA's Content Services Group didn't have much of a style guide at all or really any process in place for adopting new standards, so it's kind of like the Wild West out there, there were word of mouth best practice guidelines that writers shared with one another, but nothing formal in place as far as the style guide. In 2006, which is when I was hired as a tech writer and our group had really reached kind of a perfect storm, the company was going through a pretty heavy period of acquisitions, so we had a lot of new products and consequently new writers coming on board, so we had all that tribal knowledge on things like terminology and styling, and we just kind of shared it with one another.

[00:04:30.570] - Cathy Jones

And that had worked okay a few years before when there were only a few writers, but now they really needed to be documented formally for all the new people coming on board. And then we also had the prospect of DITA floating around in there. We knew that eventually we'd be moving our content to DITA and there would be things that we'd want to standardize and streamline as we made that change. So all those things were kind of floating around in there and that really resulted in the need for formalization. And so that's how our Style Guide initiative was born. Starting in 2006, another tech writer and I were tasked with documenting our tribal knowledge and all of these best practices that writers shared with one another. And I'll talk more in the next few slides about what we documented and how we knew what should be included. But we started out writing a few do's and don'ts very casually in word. Do say this, don't say this, do it this way, don't do it that way. Eventually, as our style guide content grew in our product documentation move to DITA, we also moved our style guidelines to DITA. And that allowed us to formalize some process and publish more easily, and it was also in this time frame that we implemented a formal editing path, we've never really had an editing review on our content before, but during this time, we first implemented a peer review system so that writers were kind of sharing their content with one another just to get a second set of eyes on it before publishing to customers.

[00:06:02.990] - Cathy Jones

And eventually that evolved into a more formal editing team. So we have a very formal editing process in place now. So all that went on from 2006 to 2013, and that was a pretty long period of development where we were just building out our style guide content, but around 2013, we got to a place where we had a pretty solid set of guidelines for our group, and we really wanted to reach out to other content creators throughout the company and establish a common set of standards for everyone. So around that time, we teamed up with folks from JHA's Marketing group, Education, Techhubs, and we worked to establish a corporate guide for everyone, all content creators throughout the enterprise. And that took some conversation and compromise, we had the style guideline that our team had put into place, but then there were other guides floating around in other groups, and we kind of had to go through a process to discuss all of that, figure out what to keep, figure out what to consolidate, figure out what to change.

[00:07:06.710] - Cathy Jones

So it was some conversation and compromise but in the long run, it was definitely well worth the effort. And we know we have a common set of guidelines for everyone. And so that brings us to present day, we're kind of in a maintenance mode right now where we're keeping our guidelines up to date and we're adding new guidelines as questions come up but really not developing a whole lot of new content anymore, so we're just kind of maintaining and I'll talk more about the processes we have in place to maintain the guide and publish updates in upcoming sites.

[00:07:43.910] - Cathy Jones

So that brings me to the main part of the session today, I'm going to share some tips and lessons we've learned over this 10-year journey that we've been on, of course your mileage may vary, but these are the things that have worked well for us. My first set of tips here have to do with what to put in the style guide and just as importantly in my mind, what not to put in the style guide. So the first recommendation I'd make is don't attempt to write a comprehensive style guide.

[00:08:13.190] - Cathy Jones

Don't set out to write something that covers everything there is to cover about style and grammar and punctuation and terminology and all of that stuff. There are a lot of great style guides out there already, Microsoft Manual style, Chicago Manual of Style and so forth. And there's really no reason to reinvent the wheel. You're not going to write a better style guide than those that are out there already. So what we did was identified a couple of these well-known guides to serve as our primary resource, that's the first place our writers go if they need some style consistency, if they need to check on something that they're writing, they go to these primary resources and we've offered our own style guide as a supplement to those primary resources. So the supplemental guide is where you'll document the standards that are specific to your team or your group or your company. This supplemental guide is where you'll answer questions that wouldn't necessarily be answered in your primary resource. So if you have a question and you couldn't go find the answer in the Microsoft Manual of style because it's too specific to your group, that's the kind of thing that you're going to put in your own style guide.

[00:09:25.450] - Cathy Jones

So what are these items that are specific to your team? What should you look at when you're making your supplemental style guide? The first one, I'd say something that we look to a little bit when we are creating our style guide was to establish a standard if there's multiple ways of doing something according to your primary guides, and they're all acceptable, but you still want to make sure your content follows the same standard all the time. Just pick one of the acceptable ways and establish that as your standard. So an example here is the serial comma, and I don't want to give off on a tangent about serial commas because I know there's a lot of strong feelings about them one way or another. But in the primary guides that we were using, there were kind of multiple acceptable ways about whether a serial comma would be required or not. So for us, we knew we wanted it a particular way, that's what we documented in our style guide.

[00:10:22.020] - Cathy Jones

Another thing that you can look to, to document in your specific style guide is wording standards. So if you have standards that are specific to your team or your group, things like product names that need to be spelled a very specific way, if there are certain words or phrases or terminology that you can or cannot use industry standards or things that you can or cannot say for legal reasons, all of those things would be wording standards that are specific to your group and then abbreviations you want to use or to avoid. A really good example of that one, one of our first style guide standards I can remember implementing was the phrase transaction code is used all over our content within our company, and it was abbreviated or spelled out just in all kinds of different ways. It would be T.C instead of Trans Code or Trans Code instead of Transaction Code or Tran Code. It was just all kinds of different ways. So that was one of the first things we established a standard for was always spell out Transaction Code.

[00:11:28.190] - Cathy Jones

Another thing that we looked for when we were looking what to document specific to our team, and this is the big one, this is where we started to get a lot of content and really fill out our style guide was to Mine existing lists. That's one of the first places we looked when we started developing our guide because our writers had a wealth of knowledge and a wealth of best practices but they were all kind of saved off on people's individual computers or lists that were emailed from person to person, or somebody had something printed out that was posted on a cue ball, or maybe it was put on some teams, one note you know, common one note or put on a SharePoint somewhere, we had all of that stuff floating around and there was so much good information there. So those were really great resources for us in the early days to find all of those guidelines, those best practices that people were sharing with one another. We went out and got those, we centralized them in a common guide so they weren't all kind of floating around and getting updated in certain places but not other places, centralized those in our common guide and kept them up to place up to date.

[00:12:37.070] - Cathy Jones

And then finally, I think probably the biggest place that we figured out what needed to be standardized, what needed to be put as a guideline in our guide was by addressing inconsistencies in our Doc. This is probably the biggest place we would get guidelines for. We'd go out and look at our documentation and look at what's varying across the different outputs and different publications. And our editing team actually turned out to be huge in this. Our editors would you know they're really out there on the front lines seeing all of our content, you know they're not seeing just one particular product content, they're seeing the content for all of our products and so they really get a big picture or view of what we're putting out there for our customers, and so our editors would come to me and they'd say well in this document it's done this way, but in this other document it's done this other way and it doesn't match up and which is right. And I'd say well, I don't know which is right, but let's establish a standard and we'll document it in our guide and then we'll know which is right and we can do it that way going forward.

[00:13:42.630] - Cathy Jones

So finally on this side, I think my last piece of advice here would be to always consider your guide a living, evolving document and don't feel that you have to document everything there is to know about your group's content on day one. You want to tackle your biggest problems first, your biggest inconsistencies, your big kind of wealth of knowledge that's floating out there undocumented. You want to grab those things first and then as you go over time, continue to circle back for less urgent items and make subsequent updates to your style guide and keep doing that over and over again until you've got everything ironed out. If you remember on the previous slide our phase of doing that, I think it went from 2006 to 2013. We just had a really long time where we were evaluating our content and building out our guides, tackling the biggest problems first and then continuing to do that over time. And then even then, once you get to the end of that and you're in more of a maintenance phase like we are now, even then a style guide is never going to be finished. Even when you've established the bulk of your guidelines, there are always going to be updates and maintenance and new questions or inconsistencies to address. So there's always going to be tweaks and your document will continue to evolve. So the tips I just went over were pretty broad, but these next couple, are going to be much more specific and they may seem like a given, but they've been important enough to our style guide that I'd like to touch on them, because I think they do add a lot of value.

[00:15:17.860] - Cathy Jones

So first, I want to suggest that you always give examples of use. Correct and incorrect use, so I've found that it's surprisingly difficult to write a style guide rule, no matter how clear and direct I think I'm being. There are always questions or alternate interpretations that crop up and people will ask a question and I'll think, what, how did you get that out of what I wrote? And so I'm never quite able to be as clear as I think I should be or as I think I am. So I think it's really valuable in those cases to have these examples to fall back on, not only of the correct way to do something, but the incorrect way to do it. A lot of times those examples are a lot more cut and dried than any guideline wording that I can put together, no matter how carefully I craft it. And these examples always come in handy as well. If we started using these examples very early on in our style guide and we stuck with it whenever possible for all new guidelines we add, and I'm very glad that we did.

[00:16:23.360] - Cathy Jones

Along the same lines, I think it's really important to make the examples meaningful for users, not only is it hard to write a style guide rule that doesn't get misinterpreted or that everyone understands, it's also sometimes surprisingly difficult to come up with example sentences. And so my inclination for examples is always to fall back on really rote basic sentences like the boy walked home from school or that apple fell from the tree. But what we've tried to do instead is to use sentences that actually pertain to our industry and to our content so that we'll have like in our example, we'll have a sentence like the United States Federal Reserve issued fraud prevention rules in July 2012. So the benefit to having that kind of example is twofold. First, it's great for me because I don't have to struggle to write my own examples. I just go out to our content and I lift a sentence that illustrates the guideline that I'm trying to write. But also I think it's easier for content creators to understand how the guideline applies to their content when the example is more realistic, when it's you know a longer sentence, a more complex sentence, it's got content that relates in some way at least to the content they're writing. That's a lot easier to apply than to try to understand it from a sentence like the boy walked home from school.

[00:17:50.280] - Cathy Jones

All right, so next I'd like to offer a few suggestions for maintaining your guide and putting some formal processes into place. So first, I'd recommend that you establish a committee to discuss and vote on style guide additions or changes, this might be something you try to do early on in your style guide initiative, but it might be something you do later after you get your most urgent known inconsistencies address with style guides, and so maybe you'll go back to this when you're in more of a maintenance mode. But no matter when you decide to do it at some point you'll want to make sure you're getting feedback from a variety of content creators to decide on guidelines. It shouldn't just be up to one person to decide what needs to be in the in the guide or how the guidelines should be worded, because you'll miss a lot of perspectives that way, you know one person getting their opinion about how things should be done that's not a very good representation of everyone who's going to be using the style guide. And ideally, if you're in a situation like we were, where there are multiple groups creating content and multiple guides floating around, you want to start the effort to keep the guidelines consistent across groups.

[00:19:05.840] - Cathy Jones

So in our case, we've got a committee of about 15 people made up of representatives from content services which is my group, education, marketing and TechPubs, we meet monthly although I do think I'm going to be changing that to quarterly since we have reached the spot where we're just kind of maintaining mostly we just often at our monthly meeting don't have much to discuss, so I think I'm going to change up that frequency. But when we do meet, we discuss proposed style guide changes and the proposals can come from a variety of places, they can come from suggestions from throughout the company, over time, people throughout JHA started to kind of associate my name with the style guide and so I'll get emails from time to time of people asking, you know if something could be added to the style guide or something could be covered in the style guide.

[00:19:57.590] - Liz Fraley

It could also be suggestions from the committee to style guide committee members if they've noticed anything on their teams or if they have any questions or things that maybe need to be tweaked in the style guide, and then finally again, issues or inconsistencies that our editors have noticed. As I said, they're kind of seeing the content from a more holistic perspective maybe than really anybody else, and so they often have a lot of good suggestions for what might need to be added or changed to the style guide. So, that's where we get our discussion points for the style guide committee meeting, and so we'll talk about the suggestion and if we do decide that a change is needed, I'll draft a new guideline and I'll bring it back to the committee for approval.

[00:20:41.270] - Cathy Jones

So the committee works out really well, I definitely suggest that you implement something like that. But I do also suggest that you have a single style guide owner or at least a very small group of people who are the owners. And the reason I say that is because there are always going to be judgment calls or interpretations to make, someone will say does my situation fall under this guideline? Or when the guide says this, does it also mean that, you know there's always these judgment calls to make. So you'll need someone to not only make that call, but also document what was decided. Either the guideline needs to be clarified in some way to avoid that confusion in the future or at the very least, whatever decision is made, it needs to be recorded in some way so that inevitably when the same question gets asked six months down the road or three years down the road or tomorrow, whenever that question comes up again, you want to try to give the same answer and maintain consistency over time on those things.

[00:21:44.870] - Cathy Jones

And that consistency is harder to maintain if there's not a centralized owner or small group of owners. And then also you need an owner or someone to drive and manage style guide updates in the committee meetings and again, the more people you have, the harder it is to move forward in a streamlined way. So having a large committee, but also having one or two people who are kind of driving that I think is a good way to go. That actually brings me to the next point, I want to talk a little bit about processes and I'll talk about what we have in place to make sure that we're updating our style guide in a organized way. So I'd recommend that you establish a specific process for updating the guide on a regular basis, you'll need to decide how often to publish your updates, what your update frequency will be, you'll need to track what items have changed with each new version of your guide and then you'll need to communicate what those changes are to your users so they're not kind of left wondering what's -- why this new version of the guide is out? What's different here? So I'll just step you through how we do that, we currently publish our style guide on a quarterly basis, although again we have skipped an update or two recently since there were still a few changes to make, so I think I might be tweaking that time frame.

[00:23:13.700] - Cathy Jones

It might go down to twice a year, but whatever it is you need to decide on what your frequency is going to be, so as our style committee meets and approves additions or changes to the guide, I keep a running list of those changes that will be included in the next style guide update. And I just keep those in a personal one note list so that's what you're seeing on the bottom left side of the screen, just a personal list for me so I can keep track of what's been changed, what's been added. And then when the publication date for the official style guide approaches I'll create a what's new page for the guide and this is what our users will see when they access the new version of the guide. So that's what you're seeing over on the right- hand side, it just lists all the changes that were made since last time and whenever possible, it includes a link to the affected section of the guide and then of course, I sub out,  I replaced the old what's new version from the previous update with this new one.

[00:24:12.330] - Cathy Jones

And then when it's time to publish, I'll post the guide on a corporate SharePoint site and remove the old version of the guide, and I post an announcement on our company's news Internet site with a link to the new guide. And something I've been doing lately, but I think has worked out pretty well is I've been creating a brief what's new video. So I'll pick the top two or three changes and I'll introduce those changes with examples in a video format, and I think a video really helps drive interest and adoption of the new guidelines and just the style guide in general across the company. So it's kind of good advertising, so to speak.

[00:24:50.690] - Cathy Jones

So that actually brings me to the end of the presentation today, I want to sum up a little bit with kind of my biggest pieces of advice or recommendations, the things that have worked out really well for us. I would first say start small, don't feel like you have to document everything all at once, start out with a complete style guide on day one, just start small, identify the most things, the things that need to be documented most urgently and brought into a consistent way of doing things, address your most immediate needs first and then continue, keep chipping away at it over time. It may take months, it may take years and that's okay, but just keep on building, keep building and then eventually at some point you'll want to formalize your update processes. So you want to put a process into place where your users know when an update is going to come out, they'll know what's changed in that update. They'll know where to get that update, so you just want to keep things very formal in the way that you're going about that so your users know what to expect. So I think that's it, Liz, I believe we have some time for questions.

[00:26:04.460] - Liz Fraley

Wow, Cathy, that was amazing, truly excellent, actionable tips for advice both for the style guide and the process running. I'm so grateful you were willing to share your experience. That was fantastic, wow! All right everybody, now it's time to type in those questions if you haven't already. And while you do, here's a look at what's coming up.

[00:26:27.060] - Liz Fraley

The TPC Affinity Groups are a monthly member-driven discussion group where attendees present their specific challenges on topics on their mind today in a confidential supportive environment, affinity groups (mastermind groups) have been cited in Forbes as being extremely valuable to attendees. We have two that are going on right now, one is everything techcomm, and the other is focused on a specific product line. It's collaborative to peer to peer environment where everyone can lend their expertise to each other. This is networking at its finest, working with your peers to solve problems and not everyone is at your company, it's important to get perspectives from people in other industries as well. You can sign up at the TC Dojo website. In our next TC Dojo coming up, we've got Kit Brown-Hoekstra former STC president. She'll be sharing productivity hacks for technical communicators, productivity, managing your time well, and knowing how to filter out the busy work sets apart the stellar performers from the merely good ones.

[00:27:24.120] - Liz Fraley

It's going to be a great session, so be sure to sign up. How do you do that? Well, go to tcdojo dot org, it's a shortcut URL that'll take you right to this page and down at the bottom you can see exactly what's coming up. We put this all down here so you'll be able to see already here. This is Cathy Session right now, as soon as the video is ready, it'll get posted there and then what's coming up in June, here's how to sign up for Kit's session. We have other related topics for you also there.

[00:27:58.950] - Liz Fraley

This is great. Cathy, great job presenting, it's so nice hearing you talk without the dead silence of some of our meetings lol.

[00:28:06.160] - Cathy Jones

Yeah, I totally agree that you are an excellent presenter.

[00:28:11.280] - Liz Fraley

All right, here's another one. Our company doesn't have global guidelines, do you have sections of the style guide that are specific to different audiences, marketing, technical documentation?

[00:28:24.970] - Cathy Jones

What we've done is we've tried to make the enterprise-wide style guide apply to everyone as much as possible. We do have certain sections in there, like there might be a section for trying to think of some examples. We've got a section on e-learning, even though a lot of groups don't provide e-learning, there is a group or two that do and so we have a section on e-learning. There's a section on like a kind of a knowledge base structure, and that applies mainly to one group. But overall, we try to keep the corporate style guide as general as possible to apply it to as many people as possible. I do think there are some groups that continue to maintain kind of their separate guides that go into more detail.

[00:29:11.860] - Cathy Jones

So like my group Enterprise Content Services, we used the standard corporate version of the guide. But then we do also have our own guide that includes DITA documentation. We didn't want to put that DITA information in the corporate guide since not everyone across the enterprise uses DITA  at this point. So we maintain those things that are specific only to us separately. And I believe the marketing team does that and probably a couple of other teams as well, but we try to make sure that even when we do maintain those separate guidelines, that there is nothing in those separate guidelines that are contradictory to the corporate guide in any way.

[00:29:52.810] - Liz Fraley

I was going to ask about that, whether you also had a tagging style guide, it's good to know that seems to be sort of yes.

[00:30:01.060] - Cathy Jones

Yeah, and what I do actually is I maintain since we're in DITA , I maintain all of this content in DITA and I publish different outputs with conditional processing so I can publish the corporate version that does not include DITA  documentation and then I can publish our internal version that does.

[00:30:21.130] - Liz Fraley

Excellent, so I see we have a question, can you give us some examples of your style guide to understand examples of what could be included?

[00:30:32.030] - Cathy Jones

Well, as I said a lot of it for us was wording and there are some things about grammar use and again do not re-invent the whole grammar wheel. There's a lot of good grammar, punctuation guidelines out there. But there are certain things, you know as far as semi-colon use that we do or do not want our content creators to do. Do you use dashes? Do you use en-dashes or em -- you know that that kind of thing where there's a lot of content out there in existing guides, but we wanted to kind of reel it in a little bit and make it a little bit more specific for us. That's in there.

[00:31:11.030] - Cathy Jones

A lot of -- kind of industry-specific things like you need to talk about this in this way, use this terminology, those kinds of things. So I guess I should have pulled up a version of our style guide on my other screen so I could take a look and thumb through. But those are the examples that are coming to me at the top of my head.

[00:31:33.080] - Liz Fraley

Great examples. I love that you have examples of correct and incorrect that is -- so I don't know how no one has ever mentioned that before, it's perfect. it's really -- I can see how that's absolutely key.

[00:31:49.270] - Cathy Jones

Yeah, and I almost didn't mention it because I thought well that seems really obvious, but then again, maybe not so much, that's something that we just kind of happened to start doing, and I'm really glad we did, and so I'm not sure if everybody does or not, so I did want to mention that as a suggestion because I think it does come in really handy. As I said, sometimes it's hard for me to envision every possible scenario or every possible interpretation of that guideline. I obviously can't, and so the examples do help a lot, and then also again continuing to tweak over time as different interpretations do come to my attention, then we can kind of reel that and even more as we need to.

[00:32:28.090] - Liz Fraley

Excellent. Here's two more questions. One, somebody would like to see samples, but I don't know if you've got that up or you can share that. But the other --

[00:32:38.720] - Cathy Jones

--Is that something that I can maybe provide to be posted out there afterwards, because that's a really good idea and I didn't prepare anything like that, then maybe I can provide something to you Liz.

[00:32:48.220] - Liz Fraley

That would be great. So folks, somebody asked if we get a copy recording of the slides and the video, it will be posted to the TC Dojo YouTube channel and the slides are already on her event page where you registered. So go to tcdojo dot org, and you'll be able to get all of those things. And that's where we'll post any follow-up information that Cathy sends.

[00:33:09.700] - Liz Fraley

All right, one last question, this is a good one. What were some of the items that were most urgent that you needed to start off documenting in your guide? Do you remember that far back?

[00:33:22.630] - Cathy Jones

That is very far back so I'm not sure if I remember too clearly, I would say a lot of it was the abbreviations and the terminology being in the financial services industry, there's an abbreviation for everything and it can be really easy to get the hang of those and think that our users are understanding all of our lingo and jargon and acronyms and abbreviations. But actually, we found that a lot of times our customers are kind of confused by that, and so making an effort to go through and standardize how we were abbreviating things and standardize on first mention, spell it out and things like that. That was a big one, I'm trying to think back we have a lot of field definitions in our content and those were often shared in different ways by different writers, so just things like that where you're making an effort to give your users a streamlined experience. So the way information is presented is the same no matter which product they're looking at or no matter which writer wrote it and just really thinking about the experience our users are having and how we can streamline that for them and make it better for them.

[00:34:42.340] - Cathy Jones

So the fields and the abbreviations, those are a couple of big examples that I can think of off the top of my head. But again I'll dig back in there, a little bit more deeply and see if we can provide some additional examples afterwards.

[00:34:55.140] - Liz Fraley

Awesome. So the one thing that stands out for me, the last thing is that I find it inspiring that you all treat this as if it's another piece of product information just as important and managed the same way and thinking about audience and you're like the video to announce what's coming up. You -- like any other product you deliver to your customers, we don't usually think of ourselves as users and we cheap out on the internal documentation. And it's really inspiring to see what you guys have done.

[00:35:30.030] - Cathy Jones

Yeah, it can be really easy to let that get to the bottom of your to do list, you know, all of us are busy, we have so many other things we're trying to do. But I do think it's important for as we said, the experience that our users are having, that they're getting something that's streamlined and consistent and they're seeing the same kind of information no matter where they look or no matter which guide they're in or no matter how they access the content, and so we've really made the initiative to put standardized processes into place just like we would with any other set of documentation. And I think that's really helped us a lot to stay organized, keep it moving forward, keep the momentum going and keep providing good documentation to our users.

[00:36:14.270] - Liz Fraley

Inspiring. Thank you Cathy for sharing your experience with us and for doing this Dojo session, everybody we'll see you again next time. That was amazing! Thank you!

[00:36:24.440] - Cathy Jones

Thanks so much Liz, thanks everybody for joining.

[00:36:27.440] - Liz Fraley

Bye guys.

View the slides

Follow-up from the presenter

by Cathy Jones

There was a question about some of the most urgent items we started out with. I went back to the earliest version of the guide that I could find. A lot of our early guidelines revolved around the following (again, based off of inconsistencies or bad habits we noted in our content):

  • Abbreviations. (We were trying to clean up abbreviations like seq. no., seq #, misc, parm, maint, TC, tran code).
  • Emphasis. (We had overuse of emphasis, and it varied from all caps to italics to bold.)
  • Field definitions. (Our core products have fields or parameters that have very specific formatting requirements regarding field length, date format, decimal positions, and so forth.)
  • Images. (We established image size, resolution, and capture standards to be sure all images looked consistent.)
  • Keyboard, button, and mouse terms and conventions (Use click rather than click on, use press rather than hit, use a plus sign to show key combinations, etc.)
  • Reports. (Many of our products produce reports, and we needed standards for how to refer to those reports.)
  • Wording/terminology standards.
    • Use select and clear rather than check and uncheck.
    • Use parameter rather than flag.
    • Use iSeries rather than AS/400.
    • Use refresh rather than redisplay.

There were a couple of questions about examples and seeing pages of the guide. I’m not sure what rules (if any) our Legal department would have about sharing our internal guide. If I present this again, I’ll work with them and hopefully be able to provide more concrete examples. In the meantime, here are some pictures of our guide’s TOC.

You might also be interested in...

Style Guides: Fashionable But Also Practical

Keith Schengili-Roberts, Ixiasoft

Topic Writing Without Borders hero image

Topic Writing Without Borders

Janice Summers, Single-Sourcing Solutions

Key Concepts:

best practices, usability and user experience, workflow and process

Filed under:

TC Dojo, Webinars

About the TC Dojo

At the TC Dojo, you pick the topics and we find the experts. Join our mailing list so you can attend the next one live. After all, you can't ask questions of a video.