Goethe once wrote to a friend, “If I had more time, I’d have sent you a shorter letter.” Here’s why.

[ad#black]

We’re all guilty of using clichés and resorting to figures of speech, especially after a long day slaving over a PC. Nonetheless, we still need to streamline our material and make sure that readers get something worthy of their attention.

Here are seven ways to cut the fat from your documents and get them back to health.

The Non-Designer’s Design Book

Let’s start.

Get a recent sample of one of your documents writing, for example, a sales letter or proposal, and look for the following horrors.

1. There are…

Avoid using this as an opener; it sounds jaded. It gives the impression that you couldn’t think of anything more interesting.

The same goes for “It is.”

These empty subjects and weak verbs add no value to your work and dilute the power of your writing. Rearrange sentences to avoid these fillers.

Not: There are now thousands of websites on the Internet.

Use: Thousands of websites are now on the Internet.

2. Ditch clichés

Make a list of your most frequently used clichés.

Paste it next to your PC, or wherever you work.

Once you’re finished drafting a document, double-check that you have not let any of these creep in.

Watch out for clichés entering your copy when you are tired, in a hurry, or impatient.

I tend to resort to clichés when I’m low on energy or waste want to wrap things up. It’s a waste of time. In the morning, I have to re-write it anyway.

Some words and expressions are so overused that they’ve been reduced to meaningless phrases.

For example:

Pre-plan — plan is fine. Can you really pre-plan?
Solution — isn’t everything a solution these days? There must be an alternative.
Seamless — is it really?
Micro Manage — manage
Access — usage, allow,
Paradigm — business model
Radical — different
Broad Range — spectrum
Synergy — connection,
Enterprise — company
Virtually Unlimited — endless
Utilize — use
Proactive — active

3. Remove what’s redundant

Go through your writing and root out redundancies, such as:

Blue in color (what else could it be besides color)
Large in size (what other kind of large is there?)
New innovation (is there an old innovation?)
End result (and the beginning result was…)
Final outcome (… was just the outcome.)

4. Be selective with Passive verbs

Passive verb tend to offer a weak, roundabout way of saying something.

In general, you can replace a passive verb with an active verb and improve the clarity of the sentence.

Not: The computer was built by John.
But: John built the computer.

5. Evil adverbs.

“Rather,” “very,” “quite”: These adverbs dilute your writing.

Cut them out and the meaning of your sentence becomes sharper and will resonate with more conviction. Poor adverbs tend to convey vagueness and a lack of interest.

Not: I was rather worried that our computers were quite unsafe.
But: I was concerned that our computers were unsafe.

6. Get to the point

We use the verb “say” so much that we tend not even to read the phrase itself.

Hemingway could get away with it, but you’re not Hemingway. Well, I’m not anyway.

Even though it’s nice to use an alternative choice every now and then, avoid using different verbs simply to get around using “he said, she said”. Constantly using different verbs in place of “say” knocks the reader off balance; it sounds contrived.

7. Jargon

Just as rappers (and their fans) used their own private language to differentiate themselves from others, companies also fall into this trap.

One of my former managers always spoke about ‘low hanging fruit.’

I bet that if you worked for the company I did, you’d have heard it.

Why?

Everyone used this on conf calls and in presentations. It was company lingo. They all used it to emphasize that there were ‘in’.

There was never a plan – we ‘transitioned’ instead.

Programmers were ‘technologists’.

It was our own private, internal language. When it crept into emails, memos, and circulars, then it could be understood. But when it appeared in customer facing reports and technical documents, then you have a problem.

3 Style Guides and Writing Books I Recommend

The Non-Designer’s Design Book

Style: The Basics of Clarity and Grace (3rd Edition)

Technical Editing (4th Edition)

What clichés do they use at your place?

Here is the simplest way to take a screenshot of a region, desktop, an entire webpage and also how to include the hyperlinks if you want to save the webpage as a SWF or PDF. We’re going to use SnagIt as our preferred tool for taking screenshots. After this I’ll walk you through more advanced features.

Follow these steps to take your screenshot:

1. Open the webpage page or document you want to capture. I’m looking at http://klariti.com/shop/

2. Open SnagIt.

3. Select a Capture Profile.

Region – use this to capture a specific part of the window

I tool a screenshot of a section of the klariti sales page.

Window — use this to capture the active window but not the entire desktop

I tool a screenshot of the klariti sales webpage, but only what was displayed on my desktop. I reduced it by 66% and cropped the edges.

Full screen – use this to capture the entire desktop

Same screenshot of klariti, but I took the entire desktop, including web browser. I reduced it by 33%.

Scrolling Window — use this to capture a window that does not fit in your monitor, for example , a webpage.

Same screenshot, but Snagit scrolled all the way to the end of the web browser. I reduced it by 33%.

You can see the entire screenshots over here on Flickr.

Web Page – use this if you want to capture a webpage and also keep it links.

Finally, I made a screen capture of the webpage. I saved this as a PDF, which retains all the hyperlinks. You can also save it as a SWF or a Snagit SNAG file, which you can edit later on.

Tip: when you choose this option, wait for a second for Snagit to start. After 2 or 3 seconds it will start scrolling down the screen, capturing the page as it goes.  Likewise, wait a second for it to open in the Image editor.

When you get there, select either PDF, HTML, SNAG, or SWF as the file format for retaining the hyperlinks.

Note that the hyperlinks in the PDF of the screenshot are now active. Impressive!

4. Switch back to the web page or document you want to capture.

5. Click Capture.

6. The screenshot is displayed in the Capture Preview window.

Depending on your setup, Snagit will:

a) Display a box with an explanation of how to complete the capture or

b) Open the image in Snagit Capture Preview automatically.

This is where you can modify the image, for example, add a border, create a nice edge special effort or save it in a preferred file format.

Profile Settings Tip: you can also click an output on the Output Options toolbar or you can automate the process by creating a ‘profile’.

A profile is a group of setting that you save so that it performs that same action every time, for example, save all screenshots in .PNG, add a 1 pixel border, and reduce the image size by 50%. Profiles are one of the best features in Snagit and saves endless hours formatting screenshots. You can setup multiple profiles and use each setting depending on the project you’re working on.

7. Click Done.

If you don’t choose an output before clicking Done, Snagit will prompted you to save the screenshot as a file so you don’t lose the image by accident.

Next

Next week, I’ll look at how to get this nice skewered effect. Stay tuned!

Looking for a simple writing tool that automatically hides your desktop so you can concentrate on your writing? Anil Atluri on Digital Inspiration has this great tutorial on how to make Google Docs your perfect free writing tool.

Turn Google Docs into a Writing Tool

Follow these steps:

1: Create a new document in Google Docs and choose “Edit CSS” from the edit menu.

2: Paste the following code into the CSS Box and save.

body {

font: 16px “Courier New”;

color: #00ff00 !important;

background: #000 !important;

width: 800px;

margin: 10px auto;

}

3: Press Ctrl + Shift + F to remove the menu bar in Google Docs and then hit F11 to turn your browser into full-screen mode.

Read more at: http://www.labnol.org/internet/google-docs-for-distraction-free-writing/10538/

Free Google Docs writing template

You can get a nice writing template over here from the same team: http://docs.google.com/

Do you use Google Docs for writing your tech documents?

What’s the one thing that would make you give up using Microsoft Word?

This is the first part in a series of lessons on how to create professional-looking screenshots. We’ll start with the basics and walk you through more advanced techniques, such as blending, merging and adding special effects to your screenshots.

What are screenshots?

Screenshot play an important part in how we read and understand technical documents.

A screenshot, also called a screen capture, or screen dump, is an image taken by screen capture software to record the visible items displayed on the monitor or another device.

Screenshots can be used to demonstrate how a program works, a particular problem a user might be having, or for training purposes.

All three terms are often used interchangeably; however, some people distinguish between them as follows:

• Screenshot – Outputting the entire screen in an image format such as BMP, PNG, or JPEG.
• Screen dump – The display system dumps what it is using internally upon request, such as XWD X Window Dump image data in the case of X11 or PNG in the case of Mac OS X.
• Screen capture – Capturing the screen over an extended period of time to form a video file. Also called screen recording.

Game screenshots

Screenshots are used when marketing video games, for example, on the packaging. Throughout the history of screenshots, there have been some deceptive practices, such as using a screenshot from a computer platform with better graphics to show how a game would display.

In the 1990s, when pre-rendered videos became a part of intermissions in games, some game boxes included screenshots from the in-game videos, which deceived potential buyers about overall game play.

Internet uses

Many web users add screenshots of their favorite movies and television shows when creating icons for LiveJournal, MSN Messenger, and Internet forums.

Employee Surveillance

Performance monitoring software now records, i.e. with screenshots, the activities of employees. The software can monitor employees through keyloggers and automatic screenshot software. Screenshots are taken at intervals to monitor employees.

Android OS

Screenshots of the Android OS can be taken by connecting the device to a computer, turning on USB debugging on the device, and running the Dalvik Debug Monitor Service (DDMS) program on the computer. Within that program, screenshots can be taken through the “Device” menu.

iPhone OS

Press and hold the Home button, then press the Sleep/Wake button. The screen will flash and the picture will be stored in the “Camera Roll” on the iPhone or in “Saved Photos” on the iPod touch. From there you can sync it to your computer.

Mac OS X

• Press Command-Shift-3 to take a screenshot of the entire screen.
• Press Command-Shift-4 to take a screenshot of a chosen area of the screen or if you press Space afterwards you can choose a window on the screen to individually screenshot.

You can also use the Grab application to take screenshots.

Microsoft Windows

Press the Print Screen key to take a screenshot of the entire desktop area. This places it in the clipboard. Press the Alt key and Print Screen to capture the active window only, i.e. the window that you’re working on. This removes the background and saves you having to crop the image.

Windows Vista

This includes a utility called Snipping Tool, which lets you take screenshots (called snips) of windows, rectangular areas, or a free-form area.

Snips can be annotated, saved as image, HTML page, or emailed

Most of the major operating systems have no built-in mechanisms to record videos of the screen (recording how the user moves the mouse around, clicks icons, types text etc. as a movie).

Screenshot software

These software packages include features such as excluding the mouse, automat cropping, timed shots and autoscroll.

• Brosix (Windows)
• Capture Assistant (Windows)
• Captus (Windows)
• IrfanView (Windows)
• SnagIt (Windows)
• Snapz Pro X (Mac OS X)
• Window Clippings (Windows)

Technical issues

On Windows, screenshots of games sometimes fail, giving you a blank rectangle.

The reason for this is that the graphics are bypassing the normal screen and going to a high-speed graphics processor on the graphics card by using a method called ‘hardware overlay’.

One way these images can be captured is to turn off the hardware overlay.

In Windows XP, you can disable this as follows:

1. Open the Display Properties menu
2. Click the “Settings” tab
3. Click “Advanced”, “Troubleshoot”, and
4. Move the Hardware Acceleration Slider to “None.”

Copyright issues

The use of screenshots may be an infringement of copyright on software programs, as it is a derivative work created by the software.

Regardless of copyright, screenshots may still be legally used under the principle of fair use in the U.S. or fair dealing and similar laws in other countries.

That’s a quick introduction into screenshots.

What I’ll do next is get started on creating your first screenshots and then start adding more and more screen capture tricks as we go along.

P.S. – if you’re having trouble taking screenshots, drop me a line and tell me what you want to do. Maybe we can help. If possible, post the screenshots on the web somewhere rather than emailing me as the email filters may not let it through.

Documents fail for many reasons. One common mistake is to adopt a ‘one size fits all’ approach to your audience. This works only when generic material, usually of a non-technical nature.

When discussing Audience Analysis, David McMurray points out that, “for most technical writers, this is the most important consideration in planning, writing, and reviewing a document. You “adapt” your writing to meet the needs, interests, and background of the readers who will be reading your writing.

Online Writing Lab makes the point that, “In order to compose persuasive, user-centered communication, you should gather as much information as possible about the people reading your document. Your audience may consist of different people who may have different needs and expectations. In other words, you may have a complex audience in all the stages of your document’s lifecycle—the development stage, the reading stage, and the action stage”

In other words, the audience of a technical document is the intended reader.

If you don’t know who you’re writing for, you need to stop and figure out why these people will read your document.

Other examples

In the same way that Disney creates movies for kids, ESPN target basketball programs at sporting types, and The Economist send their glossy magazine for executives, all of these products are targeted at a specific audience(s) and deliver accordingly.

Audience types

When you start to analyze an audience, try to identify its type. These tend to fall into four categories:

1. Executives who make decisions regarding product development and its role in the company’s overall success may have little technical knowledge but a firm grasp of how to position the product as a business asset.
2. Software developers, who are less concerned with sales and marketing activities, need to know other details, such as the specs and installation instructions.
3. Experts will have in-depth technical knowledge. They are most likely to have designed and developed the product in question. They’ll be interested in emerging trends and new technologies. How does it compare against the competition?
4. Users will have the least technical knowledge. They simply want the product to work and ‘do something’ for them. They have little interest in its business goals, marketing promises, or technical architecture. Does it help solve their problems?

For a professional writer, knowing your audience is critical. If you get this wrong, you’ll miss the mark.

Other considerations

In addition to the types discussed above, you also need to factor in their:

• Delivery – How will the document will be delivered (print, online, projection, PDA). Will it be read in the office, on the road, or in more stressful situations, for example, disaster recovery documents may be read in very hazardous conditions?
• Experience – knowledge of the application to date
• Needs – determine the reasons the reader needs to have this document and what they hope to accomplish with it.
• Preferred document type – for example, do they have a preference or a need for printed or online material.
• Training – likelihood that the person has had some (or no) training with the application. This may determine how much needs to get into the Getting Started Guide and/or the Introduction chapters.
• When the document will be accessed (work, home, travel)
• Where the document will be read
• Why the document will be accessed (reference, training)

Other factors to include:

• Age
• Culture
• Language
• Level of education
• Needs and interests
• Skills

All of those factors will contribute to how the document is written and delivered.

How to define an audience

Depending on what you’re writing, you may have just one audience or possibly several.

For example, different chapters in the TV guide will be targeted at users with simple, moderate, or advance levels of proficiency.

• How many audiences do you have? List them. Start by identifying their needs.
• What do they hope to achieve?
• What is most (and least) important to them?
• What should they do with the document?

Audience acronym

Wikihow provides this AUDIENCE acronym:

• Analysis – Who is the audience?
• Understanding – What is the audience’s knowledge of the subject?
• Demographics – What is their age, gender, education background etc.?
• Interest – Why are they reading your document?
• Environment – Where will this document be sent/viewed?
• Needs – What are the audience’s needs associated with your document topic?
• Customization – What specific needs/interests should you the writer address relating to the specific audience?
• Expectations – What does the audience expect to learn from your document? The audience should walk away having their initial questions answered and explained.

It adds that audience analysis is part of the beginning stages of producing a target document. Whereas audience analysis does help to start off the project and lead the writer in the right direction, it is only one step in the formation of a document. It is beneficial to consult other rhetorical strategies that may help guide the writing process even more so.

Advantages of audience analysis

Knowing your audience lets you refine the subject matter so that it matches the reader’s needs. If you don’t know who you’re writing to, then you can’t achieve this.

Understanding your audience is the first step towards creating a healthy document. Before you start writing, define what the audience expects from the document. Imagine how readers will use it.

For example, imagine you are writing a manual on how to tune a High Definition TV:

• What will your readers going to expect to find?
• Will there be graphics and diagrams? Maybe screenshots of how to install parts.
• What do they want to read? How to troubleshoot if they can’t find a channel.
• What do they not want to read about? Its technical architecture and business plans.
• Where are they going to read it? In their office, car, room, or even outdoors.

Here are some questions to consider when defining your audience:

• How knowledgeable is the audience?
• Before starting a project, I always ask my clients, “What do they already know?” The client should know his customer’s level of proficiency. If not, interview the target readers and determine their strengths and weaknesses.
• What do they already know? Saves you from re-writing material.
• What do they need to know? Allows you to focus on the gaps in their knowledge.
• What background material should you provide to bring them up to speed?

How to keep readers interested

Sometimes you’ll have to work hard to persuade your readers to even open the first page. Writing a grant proposal means persuading the reader that your project is worthy of investment. They’re under no obligation to read it and can stop at any time and move onto something else.

Your success as a writer depends on grabbing their attention, keeping it and then encouraging them to take action – calling the sales office, for example.

For other projects, you may have a more captive audience. Internal documentation, memos, circulars, and other such publications are all targeted at your colleagues. To a certain extent, they have read this.

But you still have to make sure they understand the material. If not, you’ll be held responsible for such poor communications. When you consider it like this, both your internal and external customers have to be taken very seriously. Just because you’re writing for your colleagues doesn’t mean you can step down a gear. Rather, you need to be vigilant and avoid complacency entering your material.

How to write different types of information

For example, if you’re updating a User Guide, you may have to highlight how it differs from previous publications. Many readers will look at the introduction only (where you’ve discussed the changes) and skip to the sections they know best rather than read the entire document.

However, if you’re writing a white paper for a conference, you’ll have different writing goals. Your aim is to get their attention and persuade them to keep turning the pages.

So, how you present different types of information really matters. Is it new or old? An appendix or update? Is it neutral (i.e. sharing information) or sales-orientated.

Here’s another angle: consider whether the publication is technical (admin guide), commercial (case study) or promotional (press release)?

When you think about it, each type of reader is very different. Knowing their expectations helps fine-tune your material. Imagine if you didn’t know who you were writing for? Where would you start?

How do readers see you?

You can’t write in a vacuum. So, how others see you will determine the tone and position you’ll adopt when ‘speaking’ to others – just as it does when speaking to people in real life.

For example: consider a business plan where you’re requesting funds.

• What’s your position to the Venture Capitalists?
• How do they see you? Inferior, superior or peer?
• What tone do they expect? Chatty, witty, and light-hearted? Maybe not!
• How about a series of Standard Operating Procedures for a Military unit?
• Again, what tone should you adopt?
• When the solders read the instructions, what attitude would you like them to adopt?
• Should they consider the SOPs politely, debate their meaning amongst colleagues, or accept it as a direct order from their superiors and act accordingly?

So, before starting, make a list of your target readers. Then, write a single paragraph outlining their needs. Prioritize their three main objectives and write your document around these. Later you can go back and refine the text to incorporate other topics that are close to their heart.

Understanding your audience is the first step in the writing process. Spend more time on this in your next writing project and you’ll see a considerable difference in the final publication.

Then go back and look at other documents where you did no audience analysis. The difference will be very obvious. Older documents will appear to be very coarse and immature; newer documents will have a more professional and solid feel to them. You know who you’re writing for and it shows.

Links:

David McMurray – Power Tools for Technical Communication

Online Writing Lab – http://owl.english.purdue.edu/owl/resource/629/01/

Ten Audience Analysis Exercises http://www.tengrrl.com/tens/013.shtml

What are your thoughts on this area? Is it best to get something written up fast and circulated or is it better to be patient and go through the analysis phase?

Master templates let you control the format and positioning of every component in your FrameMaker documents. They are very powerful when they work correctly, but be careful. If you make a mistake, it will take many an hour to clean the documents.
[ad#adc-2]
In plain English this means that if you setup a footer as Arial, size 10, and then apply it to the main document, all footers will appear in this font and this size. Sounds good!

But, what if you wanted to have different footers in the document?

You could hard code every footer.

Hard code means you manually type in the footer. That’s ok for a 5 page document but not if your creating a 250 page user guide.

You need to automate the process, which is where master templates come in.

In FrameMaker, you can create different footers, identify each type, and then apply them where you wish.

You can have different headers and footers for the:

• Cover Page
• Table of Contents
• Index
• Chapters, and
• Copyright pages.

Problems with Master Template

One of the problems I’ve had was that even though I’d created the component, it didn’t appear in the document.

The main reason for this, especially for headers and footers, was that the previous entry was still there.

In other words, you have to remove the previous header and then enter the new one.

When you think about it, it makes sense, but if you don’t know you could get very frustrated.

Tip: Delete the ‘old’ header and insert the new ‘one’ instead.

Workarounds

Numbering chapters, headers, footers, and labels can cause all types of confusion.

One trick I’ve learnt it to cut and paste template settings from a FrameMaker document I know works into the new document.

1. In the first document (i.e. you know works), open the template settings, and select the section you want to copy.

2. In the document you want to update, open the template settings, and paste where appropriate.

3. Click Apply and return to the main document. Your changes should now be reflected in the second document.

I have to admit this does seem like a lot of effort.

If you know a more efficient way to do this, please add it below.

Links

Adobe Framemaker Templates Tutorials – This Adobe Framemaker tutorial discusses the following topics: Exploring FrameMaker Templates, Modifying FrameMaker Templates, Creating Custom Templates, Using Custom Templates, and Importing Formats from a Template

How to Create a Template in Adobe Framemaker – While you can use the templates provided by FrameMaker or other pre-defined templates available to you, you may decide that you want to create your own templates. When you create a template, you can set up various types of formats based on what the template is going to be used for. For example, you may decide to create a special Title paragraph tag or table format for your template.

Introduction to Adobe Framemaker 5.0 – This is a Basic Framemaker tutorial. Look at the ‘create a new document’ to find out how to work with Framemaker templates.

Mimic FrameMaker’s Memo Template – FrameMaker’s Memo template is a great example of a template that can be used as a fill-in form. The layout and fields are pre-defined and you just need to fill in the details for each version of the document. C’mon, let’s create our own template that works in the same, wonderful way!

One File, Multiple Uses in Adobe Framemaker – XML lets you publish the same content across different media with minimal effort. And with the new XML features in Adobe® FrameMaker® 7.0, you don’t have to know XML syntax to create XML-compatible documents. Once a developer has created the structured applications, you create the content in a template using predefined element tags and save the file in XML format. It’s ready to use in an XML-savvy application or to convert into another format, such as WML or VoiceXML.