Do you think user assistance and product documentation in particular have a fashion sense? Or technically speaking, do they have a style? Do you think they have the right style? Do you need a guide for styles? Who comes up with such a style guide? Will a style guide make a difference to writers?
In one of my previous blog posts, I’ve shared the big picture about user assistance: What’s the Buzz About User Assistance? In this blog post, to answer all the above questions and more, join me in conversation with Andrea Gocke and Doug Savage, the two colleagues at SAP who work on the SAP Style Guide for Technical Communication.
1. Let’s start with a short introduction about yourselves and your roles at SAP.
Andrea: We both work for the central user assistance group at SAP. We’re responsible for the SAP Style Guide for Technical Communication, which is the mother of all other style guides in the user assistance area. My main task is to keep the content up to date.
Doug: I work on the dynamic side of things, that is, the Ask the Editors community, where user assistance developers post questions. Some of these get incorporated into the style guide.
2. What piqued your interest to work on a style guide for SAP technical communication?
Andrea: Oh, well, probably because I love standardizing things. I’m too lazy to discuss things again and again or reinvent the wheel. So why not write those standards down, publish them, and keep them up to date. I strongly believe that standardization is an 80% approach. There’s no one-solution-fits-all approach. Also, standardization has different layers: SAP-wide, product area/family, product, dev team, and so on.
Doug: As an editor, I also love standardizing things! It just makes sense. When you’re editing one-on-one with a writer, you often cover issues that should be shared with everybody. I can tell one person to use the Oxford comma, but with a style guide I can tell everybody to use the Oxford comma. A style guide is a nice efficient way to keep track of these decisions and roll them out to colleagues around the world.
3. What is a style guide and why is it important for a company?
Andrea: Style guide, guidelines, manual of style, product standards, design system, etc. Various labels are out there. Basically, it’s about having a central source of truth for standards. The label doesn’t matter. A style guide makes things more efficient. It’s a baseline for now and for the future – even or especially if some people don’t agree. Because this is the next evolution of the standard. Why don’t they agree, why doesn’t this work for them? Are there exceptions that need specific guidelines? And so on. Style guides are never stable. They evolve over time.
4. How does one go about creating a style guide? What are some of the best practices to keep in mind when creating a style guide?
Doug: We took a real community-based approach, meeting with stakeholders to put together a solid TOC skeleton, and then we added a body to this skeleton, by creating new content, reviewing/adapting existing content, and pointing to many SAP-internal sources of truth (such as SAP Brand Tools or product standards). Over time, we developed elements for formulating standards (such as an imperative do-this style, followed by an explanation, exceptions, and examples with comments). One best practice to keep in mind: Involve the people who will be using your style guide. We had an extensive review process for our style guide, and we made significant revisions based on stakeholder feedback. People are much more likely to follow a style guide if they helped create it!
5. What are the different elements of technical communication that a style guide can address?
Andrea: With the SAP Style Guide for Technical Communication being a central style guide, our scope spans the following topics:
- Audience (target groups, tone and voice, bias-free communication)
- User Interface (basics for UI text, how to refer to the UI)
- Style and Wording (basic writing principles, product names, capitalization, abbreviations)
- Structure (topic, tables, lists)
- Multimedia and Graphics
- Mechanics (language, grammar, punctuation)
The focus is broad. We often had to take the conscious decision “let’s stop here and link to the real source of truth.” Our style guide has lots of links to SAP-internal sites. User assistance is nothing isolated, you also need to familiarize yourself with UI design or release management, for example. We also have a standards and guidelines overview page, which provides links to style guides for specific user assistance tools, types of user assistance, or for specific product families.
6. How do you make colleagues aware of the style guide within a company?
Doug: By involving them in the update project (our major overhaul of the style guide in 2014/15). They can also provide feedback directly through the commenting function in the style guide. And then there’s also the Ask the Editors community, where people can ask questions.
7. How do you ensure that the style guide is relevant and updated with the various changes and trends in technical communication?
Andrea: The style guide evolves over time. Issues will come up, colleagues approach us through various channels (phone, email, internal communities, comments in the style guide itself). Trends and standards are something different. A standard is a fairly stable thing (based on previous discussions and alignment) whereas trends are dynamic. They are momentary things but can evolve into standards.
8. What do you see as the future for the style guide, maybe 10 or 20 years down the line? Would the format be the same or do you think it would evolve into something new altogether? Share your imagination with us.
Andrea: Lorem ipsum dolor sit amet I’d say. Well, I’m not the visionary type. It seems as if ChatGPT and friends will revolutionize the way of writing. Maybe we don’t need style guides any longer or we’ll need different types of style guides. The writer’s focus will be on revising generated content (correct? relevant for target group?), less on the automated mechanics of grammar, spelling, punctuation. I can’t say but I think or maybe hope that there will always be people who want or need to understand the underlying rules. And that’s what a style guide is for. I’d even dare to say that this is not only true for style guides.
Doug: I agree, it’s hard to predict what will happen. But I can imagine a future style guide that is less of a document and more of a bot that has style standards programmed into it, maybe using AI and machine learning to detect when your writing isn’t following SAP style. You could run content through it and get a little report on style problems. Or maybe it could give advice in real time, while you’re writing. Hehehe now that I say that, it sounds pretty annoying! Maybe it will be useful AND annoying? 😊 And the rules will change with the times. In the future, the rules might be less about stuff like punctuating lists and more about... proper emoji usage? Dress code guidelines for virtual avatars? We'll see! For some reason, I like to think that we’ll still be arguing about hyphens and commas, even when we all live on Mars! 😊
And with that folks, we come to the end of the interview! Did this blog post help you gain insights into the why, what, and how of a style guide? Do you feel a style guide is important? Share your thoughts using the comments. Know anyone who would benefit from this blog post? Feel free to share it with them!
About the Author
Vaishnavi is a user assistance developer and information architect at SAP and has written several blog posts on information architecture and user assistance. She has worked on several SAP solutions on S/4HANA, S/4HANA Cloud, and Business Technology Platform (BTP).
You can follow her on: SAP Community | LinkedIn
