I work in a medium-sized engineering software company in Italy. I’m one of two technical writers and the only native speaker in the entire company. The company has 2 products, I write for one, my colleague writes for the other. For the both of us this is our first foray into technical writing. The problem is we have two radically different approaches: I’ve read a variety of style guides (MS, Gnnome, CMS etc…) gone to conferences (TCUK, UA Europe), my colleague has never read a style guide, although now she is opening up to my ideas. The end result is 2 product guides with two very different writing and graphic styles - the tone and look feels like don’t come from the same company.
I have to make a pitch to management to try implement some sort of style guide so that our documentation is consistent throughout - also for any future TWs who come to the company. I have to give a presentation to those who count on the merits of creating (copying from others) and implementing a company-wide style guide but have no idea how or where to begin. I have about 20 minutes to make my pitch. Has anyone been in a similar position? Does anyone have any ideas as to how I can make my point without offending anyone or passing judgement?
I really appreciate any feedback.Thanks
It’s been years since I’ve had to justify a style guide to an organization. I would google “why I need a style guide” and start from there. A couple of arguments you can use:
- Increase brand awareness
- Improve consistency
- Reduce costs (if you are localizing)
- Reduce customer confusion (esp if said customers use both tools)
Generally, you start with a guide (for example, the Microsoft Manual of Style for Technical Publications, and then document the things YOU do differently. For example, the MS guide may say to click buttons and you may decide you want to select buttons (not that I agree with that difference, just an example). So you guide would note “buttons, select, do not click” and “select buttons, do not click” or something similar. You do not need to reinvent the wheel.
Do plan to update the guide periodically. If you can use a collaborative tool (Google Docs, Sharepoint) to keep your version of the guide online, you can update it on a regular basis. Otherwise, keep notes and have a monthly or quarterly meeting to discuss changes and additions.
Make the guide available to everyone in the company. This way, all marketing collaterals, website content, and so on matches. This means things like “email vs e-mail” and “internet vs Internet” are resolved, too.
The guide should be an evolving thing but it should be something that everyone conforms too. And you will offend and you will be passing judgement. So get over that – people who think they don’t need a style guide need to understand they why aren’t good writers without one.
This is just a start… google around and you’ll find some good examples! Use the Chicago Manual of Style also for just plain good writing (in English!).
Thanks. The thing is, technical writing is an actual “profession” in most parts of the world - in Italy it’s only just starting out and believe me, no-one really knows what it involves. Before I came along, no-one knew that style guides/manuals of style existed. I generally stick to the MS style guide and use CMS and AP as back up - and now this forum. I guess my problem is not offending and passing judgement. I’m on the same level as my colleague and so have no authority over her so I’m limited in what I can do. So far, I’ve managed to get her to change very little of her “style” and I guess this presentation is an attempt to get others to see what I’m trying to achieve.
I also do some work for the marketing department and meet resistance all the time.Italians have a very florid writing style and the simplicity and clarity of English leaves them baffled. I’ve spoken to Marketing and they don’t think they need a style guide, because, you know, it’s “marketing”. Do you see what I’m up against? So, I’m just sticking to the technical writing side for the meantime.
I’m rambling. I guess I’m actually just looking for confirmation and some ideas. Thanks Sue
If the looks of the docs are very different you have a great opportunity–just make side by side screenshots, then point out that a customer could think they came from two totally different companies. Maybe put in some marketing razzle-dazzle about brand, and how the docs should reflect the company brand, which means we all use the same language and graphics. Even if you don’t like what your Marketing dept would pick, they still probably have an opinion about whether your company style is formal or casual, and whether the audience is international and therefore needs simpler or less idiomatic language. Consider your customer’s path through the corporate website and the docs and how much easier it is if all those things match. And how easy it is for new writers to learn how to write about your products–that is money you save on training. If you can get buy-in on that, then maybe you can get buy-in on specifying what the button clicks are and all.
I don’t think you need to use the word “style guide” if that puts people off. You could call it “terminology reference” or “pattern library” or something.
Your suggestions were very useful. I’ve practically finished the presentation and I’m very happy with it. I just hope it goes well.
It is definitely easier to start a style guide when there is buy-in from your writers! We update our guide constantly, and I try to always solicit feedback from our writers when we do. Have you tried sitting down with the other writer to see where the differences are, what her preferences are, her must-haves, etc? I bet if you walked through your big concerns together, you could compromise on several things.
Ultimately, the guide doesn’t have to match Microsoft’s or anyone else’s, it just has to be consistent between the two of you. If you build it together, based on a middle ground of what you’re both already doing, she will likely be more invested in improving it moving forward.
Once you have her buy-in, she can help you present your goals/guide suggestions and two’s better than one!
I know I am a bit late in replying but you may try creating a POC with styles applied and then compare the difference. Just a couple of pages would suffice.
I actually have sat down with my colleague on several occasions. She’s quite open to everything I say but it’s quite another matter when it comes to putting what I say into practice. I’m working on it.
Today I managed to convince her that I can be the style guide administrator and she can work on a common stylesheet - that way we’re both doing something positive towards getting consistent documentation. She was very happy about that.
Oh! I forgot! Mandar thanks. I managed to create a POC and it works really well. Great advice
I would like add one more thing.
Implementing styles at one go can be pain. You may create a roadmap for docs where in you explain how you are going to implement the changes in phases.
I have recently joined a startup and this is one of the issues I am facing here. I have documented my experience here - https://mjtechblog.wordpress.com/
I don’t know if anyone’s interested, but I thought it only right to let you know how it went. Sorry it took me so long!
The presentation went really well. The CEO was really impressed and all those present were really excited to hear what I wanted to do. To cut a long story short, I’ve been given free rein to write a company style guide and have been given full authority to see that people are using it. I created a road map that was acceptable to everyone, organized meetings to get all the information I need and most importantly I’ll be holding a series of “tone and voice” meetings so that we can establish what our style is once and for all. Once it’s done I’ll be doing some workshops to help people (a reminder - I work at an Italian company) implement the guidelines.
Thanks again to everyone who responded to my plea!
Thats really great!
Congratulations to you
Do keep posting your findings/progress and share with us. It will be a good learning experience for all.
I wandered away and never saw this follow-up, but what a great outcome!