Golden rules of content for 2013!

Looking for the “Golden Rules” of content for 2013? Look no further! We have gathered them all for you in one convenient place. Many thanks to our friends and colleagues from around the globe who shared their visions, ideas and thoughts about the future of content in 2013 and beyond.


1.  “Brevity! Remove all the ‘extras’ while you are doing your last pass. Be careful using spell check - you may inadvertently create very peculiar content. Single source wherever, whatever and whenever you can.”

 -- Debbie Zioni, Documentation Manager at Kaltura

2.  “Simplifying your content makes expert users. Complex, long drawn out, never ending, convoluted, intricate, longwinded content is simply confusing.”

 -- Deborah Landau, DB Programmer and Tech-Tav Technical Writer

3.  “Write less.”

--Rebecca Rachmany, Tech-Tav CMO

4.  “In a world of Simplified Technical English, it is not advisable to use hifalutin words in your User Guides. For example, marriage. It is not recommended to write a sentence where ‘x protocol is married with y approach to produce z customer experience’. Romance has no place in documentation. However, it is permissible – and even desired – to use ex-boyfriends’ names in screen shots.”

-- Sarah Kaye, Documentation Manager at Jungo, now part of Cisco

5.  “KISS Keep It Simple & Succinct. With Ice Cream Sandwiches, Jelly Beans, & Pandas in tow, user documentation should be FUN Fast Useful Nuggets of information.”

-- Shifra Heftler, Sr. Tech-Tav Technical Writer

6.  “Keep presentation ‘bells & whistles’ to a minimum. More special effects means, longer time to prepare, test, troubleshoot, modify, and maintain.

-- Leybl Botwinik, Documentation Manager

7.  “The less you write, the more they read. Too many words are too hard to absorb. We're writers, we love to write, we love words, and we know thousands of adjectives, synonyms, and similes. Lose the words. Think about what you are trying to say, focus on what the reader really needs to hear, and say it clearly.”

-- Adina Sherer, Sr. Tech-Tav Technical Writer

8.  “Never write a paragraph when a bullet point or two will do the job.”

-- Ezriel Yellin, Techshoret Founder, Sr. Tech-Tav Technical Writer

9.  “Write simply and clearly. Loquaciousness obfuscates the intelligibility of the prose.”

-- Jeff Klein, Sr. Tech-Tav Technical Writer

10.  “Just because we don't pay printing costs anymore doesn't mean we can be verbose. If you wouldn't pay for it, don't write it.”

-- Ben Mansheim, Documentation Manager at Tufin

11.  “Make sure that whatever you write, it's clear, concise, cogent and correct enough that your grandmother can understand it. Even if it's a technical subject, if she can't understand what you are writing about, then nobody will understand it.”

 -- Danielle M. Villegas, and web publisher consultant for BASF in 2013

12.  “No xrefs, no links, no jargon. Re-read everything you write several times. If your grandmother can't make sense of it, then try again.”

-- Mark Novembrino, System and Information Architect at Number 9 Solutions

13.  “If you don't understand what you wrote, no one else will. To write clearly, first make sure you understand your content.”

-- Shira Rosenfeld, Technical Writer at Check Point Technologies

Your users could be in Kayoto, Kalamazoo or Katmandu and English may not their native language

14.  “Be sensitive to language and cultural differences. For example, use 3-letter month – is 8/12/2012: 12-Aug-2012 or 8-Dec-2012?”

-- Leybl Botwinik, Documentation Manager

15.  Just because you're a clever writer doesn't mean you have to write cleverly. Keep it simple, many of your readers are not native English speakers.

 -- James Kilner, Sr. Tech-Tav Technical Writer

Have a sense of humor

16.  “Documentation for Agile Development – where your content is obsolete even before you have written it."

 -- David Danziger, Tech-Tav Technical Writer

17.  “The Prime Directive: Never write an unnecessary word. How?
 a. Understand your user's goal.
 b. Consider what your user already knows.
 c. Tell your user PRECISELY what they need to know/do to reach their goal.
Mandatory punishment for wasting your user's time with superfluous information: a year's hard labor fixing 7,000-page locally-formatted, manually-numbered hardcopy documents, where the SMEs laugh at you and the PM insists on perfection...tomorrow...even though 'nobody ever reads the manual'...”

-- Cara Bereck Levy, Technical Publications Manager at Unitronics

18.  “It's been said that a million monkeys at a million keyboards could eventually produce the complete works of William Shakespeare. For faster results at a more cost-effective price, forget the team of monkeys and just hire one really good, highly qualified writer.”

-- Victoria Feinerman, Sr. Tech-Tav Technical Writer and Voiceover Talent at Victoria’s Voice


19.  “There is much skill in asking the right questions. If you want the right content, learn to ask the right questions. In the age of information, the right information is a rarity.”

-- Rochelle Lev, Senior Technical Writer, Tech-Tav Documentation, Ltd.

20.  “If a product’s feature does not make sense to you, even after 2 or 3 explanations, then something is wrong with the feature, not you. It will never make sense to the user. However when presenting the product’s ‘bug’ to the developer, do so as part of the team. Remember, you are working with him/her, not against him/her. Always see yourself as a member of their team. Your goal is to cooperate not to aggravate.”

-- Monica Haber, Sr. Tech-Tav Technical Writer

21.  “Never tell a developer that s/he’s wrong – they can’t handle it in most cases and the blowback isn’t worth it.”

-- Oren Iny, Manager, Information Development at BMC Software

A picture is worth a thousand words

22.  “Cut the words down, add clear informative graphics, and select the most appropriate delivery medium.”

-- Adina Sherer, Sr. Tech-Tav Technical Writer

23.  “If a picture is worth a thousand words, put in a picture when it can save a lot of text.”

-- Ezriel Yellin, Techshoret Founder, Sr. Tech-Tav Technical Writer

24.  “Give graphics a logical file name and try and combine a few screen captures into one composite graphic.”

-- Rivka Bernstein, Documentation Manager at Pontis


--Yaël Berlinger, Content Development and Instructional Design at Verint Systems Inc.

Good documentation saves your company money

26.  “There are no stupid questions – just bad documentation that inspires countless calls to a company's help desk.”

-- Victoria Feinerman, Sr. Tech-Tav Technical Writer and Voiceover Talent at Victoria’s Voice

27.  "Good documentation not only provides solutions to customer problems, it saves your company IT support time and costs."

-- Michelle Friedmann, Sr. Tech-Tav Technical Writer

28.  “Useful content is a wonderful thing. It minimizes your support load, it buys you loyal customers, and it sells your product. All that is true only if you actually deliver the content to the customer. If you’re spending 80% of your content budget arguing over your delivery format and only 20% developing your content, something somewhere is wrong…and your customers will lose out most of all.”

-- Sara Levy, Sr. Tech-Tav Technical and Marcom Writer

29.  “Customers want to hear about what you can do for them. So go easy on the I’s”

-- Nettie Feldman, Tech-Tav Marketing Writer

30.  “When you’re creating content for users always think not what you can do for the user,
but what the user actually needs from you.”

-- Yoni Palmer, Documentation Manager at ECI Telecom

31.  “Remember to focus your information gathering on getting the content your users need. Don’t waste their time with things they already know or don’t need to know but are of interest to you as the writer.”

-- Tamar Pierce, Sr. Tech-Tav Technical Writer

Managing the documents and the people

32.  “Tools are wonderful, but people are essential. Avoid putting tools before people when it comes to content aggregation and cultivation. Use tools to their maximum capabilities. But remember to schedule time to walk the floors of your organization. Knock on doors, strike up conversations in the canteen, kitchenette, car service, and beyond ... wherever colleagues congregate and share stories. Then go ahead and build those stories into knowledge sharing articles. Now, you can use your tools to help you do all the important tasks that a Knowledge Manager does each day: blog your story, put it on a Wiki, on a PHP community bulletin board, Tweet it, tag it with bookmarks and categories, respond to comments ... and use "traditional" tools like email to drum up interest, draw attention, and disseminate virally.

--Dave Egyes, PD Documentation & Knowledge Sharing at Cisco

Organize your content and make it accessible to the reader

33.  “The visual presentation of content is not unlike a great feast arranged so that you can tell at a glance what is being served.”

--Janet Weiner, Sr. Tech-Tav Technical Writer

34.  “ For large documents, consider the Table of Contents to be a map – will your reader be able to navigate it easily and get to what s/he needs?”

-- Leybl Botwinik, Documentation Manager

35.  “Understand what the final documentation product needs to look like before your begin. Store content for the project in a logical and easy to access system. This also allows you to collect content for a section of the project that you might not have started working on.”

-- Rivka Bernstein, Documentation Manager at Pontis

36.  “Plan ahead: find the best solution to update quickly for new versions, to release fixes for older versions, to assimilate more people and projects, and to handle globalization. Don’t believe anyone if they say the perfect solution is … X. Find the solutions that fit you. Think outside the box. Use R&D to implement what you dream of.”

-- Rochelle Fisher, Technical Publications Team Leader at Check Point Software Technologies

Editors and proofreaders and QA, oh my!

37.  Never publish something without having another writer at least glance at the content.

-- Oren Iny, Manager, Information Development, BMC Software

38.  "Be humble and let your ‘editors’ do their jobs - be it the project manager or software engineer. Your expertise is to help your audience understand the product in a clear, succinct way; theirs is making sure what is written is accurate. Know how to take criticism and suggestions but also know when to stand up for things that you know are correct in your field of expertise."

-- Judy Shaltiel, Tech-Tav Technical Writer

39.  “Never publish content before it has been reviewed and tested! The best way to QA content is to have someone, who has never seen this software/feature before, read it and try and follow the directions. If they succeed, then you have succeeded in getting your point across. It is always better to take the time to read and test what you wrote before it goes out to your users.”

-- Rachelle Cohen, Sr. Documentation Editor (Creative) at MediaMind


40.  “'I'm a technical writer, so why should SEO interest me (and my employer)?’ Does your documentation appear in the Support section of your company's website? Learn and implement 2-3 basic SEO principles to adjust your content slightly and enhance your company's ranking for important keywords and phrases.

-- David Rapport, Freelance Technical and Marcom Writer living in Jerusalem


41.  “Your readers really do ‘RTFM’ when they're stuck and when they're installing your product. (Hat tip to Sharon Burton). Therefore, think carefully about usage procedures, making them well-organized, concise, and meaningful to a potentially frustrated user. But think more about your installation and troubleshooting sections as well.”

-- Jodie Quinn, Tech-Tav Technical Writer

42.  "Measure. Make sure your wiki or HTML has an analytics feature built in so you can find out what pages users are viewing, what paths they are following and what pages they never see. If you can, put in a feedback button to find out if the topic was actually helpful. You don't know if you are serving your customer unless you have a feedback mechanism."

--Rebecca Rachmany, Tech-Tav CMO

43.  “Shift of importance in content types: With products being more complex and more user-friendly, it’s almost more important to explain WHAT a product does and WHY you need to use a certain functionality, than [the obvious] HOW to make it work.
Content visualization: Users are flooded with information and have less time to learn new technologies, so help them grasp your content quickly by providing plenty of visuals (diagrams, cartoons, animations, videos).
Content management technologies: Prefer those that give value to the user to those that focus on authoring conveniences.”

-- Erika Yanovich, Manager, Technical Documentation Department at RAD Data Communications


44.  "Don't stop caring. I think it's what separates the greats from everyone else. You need to care about your work, and take pride in what you produce, otherwise technical writing becomes just another job, and your work is never at its best.”

-- Yehoshua Paul, Documentation Manager at Galor Systems.

And these rules just makes good, plain, common, documentation sense

45.  “You know something is wrong when a user is lost without a search feature. It's called a guide for a reason.”

-- Ashira Kosbie, Tech-Tav Technical Writer

46.  “Remember: you are the user's advocate. Technical writers translate engineering-speak into words that the user cares about.”

-- Yehudah Goldberg, Tech-Tav Technical Writer

47.  “Always break your content into reference, task, and concept type topics.”

-- Oren Iny, Manager, Information Development at BMC Software

48.  "Declutter frequently so you are not left with too big a mess at any given point."

-- Michelle Min-hahar, Sr. Tech-Tav Technical Writer

49.  “There is no such thing as perfect content, but some preventive action is always useful: Follow these 5 ‘Content’ rules: Correct, Clear, Concise, Consistent, Checked”

-- Leybl Botwinik, Documentation Manager

50.  “An awesome technical writer embraces the fact that their users don't want to open the manual until they can't figure it out by themselves. But when that happens, the awesome technical writer facilitates the quickest route to the information.”

-- Naomi Papoushado, Tech-Tav Documentation Warrior

51. "Don't let your tools dictate how you build your content. If the content doesn't fit the tools, fix the tools. Don't structure your content based on historical reasons. "That's the way we've always done it," is an irrelevant argument unless you understand why it's always been done that way".

Benjie Wolicki, Sr. Technical Writer

Now we need to hear from you! Please leave us your “Golden Rule” for content in the comments section below...