7 Steps to Clear Technical Writing November 23, 2006
Posted by iawalsh in : How do I ?, Writing, Style, Templates, Recommended, Tips , add a comment
When you write a technical document, consider the following points:
-
Glossary – make a glossary, even for a half dozen words.
-
Definitions – create a list of definitions and acronyms. Always explain what the acronym means when it’s first encountered.
Use bold for the definition or acronym to make it easy to find it again. -
Analogy - provide a comparison or analogy.
-
Graphics - Provide graphics to illustrate the object in question, how it is assembled, or how it is used by operatives.
-
Replace general, abstract, and needlessly objective words with more concrete, specific, and simpler words.
-
Break long sentences into shorter sentences.
-
Use terminology consistently.
These points are not meant to be all-inclusive. However, if you are new to tech writing, this should put you on the right road.
How To Write An Annual Report November 22, 2006
Posted by iawalsh in : How do I ?, Writing, Style, Templates, Recommended , add a commentA successful annual report contains the following key elements:
1. Visual appeal
What is the look and feel of your annual report? Is it attractive, interesting and unusual, or boring and unimaginative? The clever use of design, graphics, artwork and typography can make the difference between a winner and an also-ran.
2. Good readable text
Don’t be tempted to choose a fancy typeface that will be difficult to read. Remember your aim is to disseminate your information - it will not happen if the document is set aside because the words are illegible.
3. User-friendly
The document must look AND BE easy to read. Write it in plain English (or the language of your choice) and take care that the lay-out has plenty of “white” space to give the eyes a rest.
4. Length of document
Do not make it too long. In today’s information age with instant information on the web, the last thing people want to do is to wade through endless pages before they reach the relevant information. On the other hand, the document must not be so concise that it does not cover the important sections.
5. Credibility
Credibility, once lost, is just about impossible to get back. Take care to back up your statements with facts and refrain from wild and untruthful statements - even if you think nobody will know better.
6. Planning
Your planning should not only focus on what you want to say in the annual report, but include the production cycle of the writing, printing and distribution of the report as well.
7. Paper quality
When selecting the paper for the report, keep your end-user in mind. Do not save money by using paper of an inferior quality on a project of this importance. Nowadays, recycled paper is very in vogue, but it must enhance your message, not detract from it.
8. Images/Photographs/Graphics/Maps/Illustrations
Your images must compliment your text. Full-colour photographs are the norm. Use a B/W photograph only when you can be assured that it will have the right impact. Although graphic images, maps and other illustrations usually enhance your site, too many can have the opposite result. As with most things in life, too much is not good.
9. Budget
Budget - control it, don’t let it control you. Know your options and get quotations before you agree to anything. Above all - set a realistic budget.
10. Feedback
You’ve written the annual report, it has been printed and posted. Now you can sit back and relax - or can you? How do you know whether the report achieved its objectives. Is there room for improvement? Feedback on your annual report is almost as important as the report itself, because it will lead to possible reviews, amendments and improvements.
How to Write Emails That Get Results November 20, 2006
Posted by iawalsh in : How do I ?, Writing, Style, Templates, Recommended, Tips , add a commentI receive close to 60 emails a day. Some are one-liners, which require a simple answer. Others are more detailed and require some thought and analysis before answering, while the last group can be very lengthy emails that ramble from one item to the next and to the next and…Time counts in business. Finding ways to streamline or automate your daily tasks lets you focus on more pressing matters.
In the following tutorial, I’d like to offer some tips on how to write more effective emails and also—what you may find more interesting—how to respond to them so that you receive less emails and those you do receive from your colleagues become more structured. Needless to say, these suggestions are aimed at business people and not your daily chit-chat with friends.
How To Start Your Email
Depending on the type of email you’re writing:
-
if it’s the first time you’re writing to someone, introduce yourself and state the nature of your business. Use simple everyday English, but stick to the point. Don’t apologize or ingratiate yourself for writing an email if it has a business purpose. Also don’t ramble or try to become ‘best buddies’ with this person.
-
if you’re replying to a response they’ve made, thank them for making the effort. A simple acknowledgement is always appreciated.
How to State your objectives
Every email has a goal. Many emails are requests. They’re asking the reader to do something. Attend a meeting, write a report, provide feedback, submit documentation and so on.
You can make life easier for the reader by highlighting what you’re expecting them to do.
-
Use headings to state your objectives
Instead of writing long convoluted slabs of text, divide your material into short paragraphs each with its own heading. Not only with this help the reader grasp the key points, it will also help to revise your own emails.
Write short 3-5 words headings. Use simple english. Avoid puns, wordplay or jargon.
-
Explain your objectives in detail
Underneath each heading outline what needs to be achieved. When dealing with complicated matters, clarify for the reader who’s responsible for which task. Ensure that the reader understands what’s being asked of them. Again, use a civil tone.
-
LIst tasks and goals
In detailed correspondence, you can further clarify matters by listing the items that need most attention. If necessary, list them in order of priority. By doing this the reader can scan the email – most of us don’t read word by word - and zoom in on the key points. Using lists is a great way to highlight and prioritize requirements.
Tip: If you take the effort to do this, the reader will eventually start to copy this structured writing style. Most people haven’t been trained to write. But they know good writing when they see it – it feels right - and will start to imitate it. In the long run, you’ll receive shorter, more accurate communications. And if you’re working in a team, almost by osmosis, you’re productivity will improve.
-
Set expectations and provide timelines
This is where most people fall down. After taking the effort to introduce the subject, highlight the main issues, list them by priority, they overlook one critical step.
Tell the reader why they need to respond.
Tell the reader when they need to respond.
By telling the reader why they need to respond, you’re highlighting the value of their role while also motivating them to make the extra effort.
By telling the reader when they need to respond, you’re reminding them that other activates may not be able to progress until they have replied. You can reinforce this point by highlighting the ramifications of such inaction on their part. Again, be careful how you phrase it. But don’t assume they know the importance of an email unless you tell them.
-
Summarize and signoff
Don’t repeat yourself for the sake of it. If you’ve used headings and lists, the reader will understand what’s required of them. Thank them and move on.
-
Provide Contact Details
This sounds obvious but not everyone provides contact details in their email. There is no excuse for this type of laziness. Learn to create a signature file. If you use Microsoft Outlook, go to Tools, Options, and click the Mail Format tab. In the Compose in this message format list, click the message format that you want to use the signature with. Add your job title, email address, and phone numbers.
You don’t have to use emails for all business communications. Pick up the phone and talk to people. Use emails where appropriate but consider other channels too. Talking is often more productive, especially if you need a simple yes/no answer.
As mentioned in difference places above, tone is important in all business correspondence. Tone is the voice you use when writing. It can be warm, friendly, blasé, curt, blunt or patronizing. It all depends on the emotional attitude you take with your reader.
In the business world, it pays dividends to develop a writing style that encourages others (especially those you will never meet face to face) to proactively communicate with you. Developing a successful writing style takes practice. We’ll talk more about tone in the coming weeks. For now, start using heading and the occasional list in your emails – you’ll see the difference very soon.
Save As Shortcut November 20, 2006
Posted by iawalsh in : Misc, How do I ?, Writing, Cool Tricks, Tips , add a comment
Save As ShortcutRather than going to the file menu and clicking File and then Save As, try the following shortcut.

-
On the keyboard, click F12.
This opens the Save As dialog box. -
Save the file with a new name.
Go To Shortcut
Rather than going to the Edit menu and clicking Go To, try the following shortcut:
-
On the keyboard, click F5.
This opens the Go To dialog box. -
Enter the Page number you want and then close it.
Changing the Cursor
Did you know that you can change the cursor on your PC?
The cursor on your computer is probably a thin black line. This is the default cursor on most Windows machines and for most of the time it’s fine. How about if you want something else? Try this:
-
Hold down AlrGr and then press the – symbol (right of 0 on my keyboard). This changes the cursor to a - sign.
-
Hold down AlrGr and then press the + symbol. This changes the cursor to a large + sign which may make it easier for you when writing documents.
Using Paint to take Great Screenshots November 20, 2006
Posted by iawalsh in : How do I ?, Formatting, Writing, Style, Microsoft Office News, Cool Tricks, Tips , add a comment
There are many great products for taking screenshots out there. Snagit is the one I’d recommend most.
However, if you’re on a tight budget, you may have to make do with Paint, which comes pre-installed with Windows.
Paint is a very under-rated product and comes with more features that you’d probably expect. If you learn to use it properly, it will probably save you having to buy a specialist product.
So, what I’m going to do is show you how to take nice, clean screenshots with Paint.
How to take a standard screenshot
-
Open the page, image or website that you want to take the screenshot of.
-
Press the PrtSc key on your keyboard.
On my laptop, this is above the letter F10. On my desktop, it’s between the keys and the number pad. This takes a screenshot (like a photograph) of the entire desktop.
Later we will look at how to screenshot floating windows, where you have many items floating above each other on the screen at the same time, such as pop-up windows. -
Open Paint. Use Ctrl + V to paste in the screenshot.
Let’s say that you only want the logo and not the entire page. To do this, use the Select tool. -
Select the area you want to extract from the image, i.e. the logo.
-
Press Ctrl + C to copy the logo to the Clipboard.
You now have a large image with a hole in it where you’re logo used to be. What we want to do next is remove this image, copy the logo back into Paint, and do some tidying up. -
Press Ctrl + A (to select the work area in Paint) and press Delete. This wipes the screen clean.
-
Press Ctrl + V to paste the logo back into Paint.
The next step is to tidy up the image. -
Use the Select tool again and drag a thin box along the edge of the logo.
-
Press Delete to remove the area you selected with the box.
You can repeat this step to tidy up the image. -
Use the Select tool to select the image.
-
Press Ctrl + C to copy the image and then paste it into Word or whatever program wants to use it.
Using Paint to Convert Images into JPG, TIFF and PNGs November 20, 2006
Posted by iawalsh in : How do I ?, Formatting, Writing, Style, Templates, Troubleshooting, Cool Tricks, Tips , add a comment
You can use Paint to convert many graphic files from one file type to another. You don’t need to buy Adobe Photoshop or other expensive graphic design tools. Paint has many small tricks up sleeve.
You can open these file types in Paint:
-
BMP
-
JPG
-
TIFF
-
PNG
You can save the BMPs (also known as bitmaps) as Monochrome, 16 colors, 256 colors, and 24 bits depending on the type of image you want. For example, if you’re creating documents that will be printed in black and white, then saving the images in Monochrome will significantly reduce the file size.
You can convert these files from one type to another. This means that you can convert, for example:
-
BMP to JPG
-
JPG to TIFF
-
TIFF to PNG
-
PNG to BMP
And all the different combinations that these offer…
If you’re creating web pages, I’d recommend using JPGs. These provide high-quality images that take up a small amount of space. You can also cut and paste them directly into Word and other Office applications.
How To Write Headings November 20, 2006
Posted by iawalsh in : How do I ?, Formatting, Writing, Style, Templates, Recommended, Microsoft Office News, Cool Tricks, Tips , add a comment
The earliest memory I have of writing is producing a very long and serious essay on Hamlet. I managed to write eight pages. The teacher wanted 2000 words – minimum. So, we all churned out hundreds and hundreds of words. Did anyone read it? Probably not.
Maybe you wrote something like it too. Do you remember what it looked like? Think back. Long, heavy, dense paragraphs, all written in long-hand. Easy to read? My essays (maybe yours were better) never used a single heading. Large slabs of text. Starting with the introduction (Hamlet was the son of…) it galloped headlong towards the end (…which is why he died!).
In academic writing, particularly ‘creative writing’, you can get away with such things. What’s important is that you get your feelings and thoughts down on paper.
Business writing is very different.
Unlike academic writing, in the business world you have a very attentive audience, some of whom have paid money to buy your products! They expect you to tell them how it works, which only seems reasonable.
A lot of my time is spent editing other people’s work. One of the quickest ways to get started, or at least get into the document, is to introduce strong headings. These add shape and confidence to the document. Suddenly it has structure. A framework begins to emerge.
Why Write Headings?
Knowing how to write clear, informative headings will make a great difference to your documents. Headings are like sign-posts. They tell the reader where to go. They call out and say, “This paragraph is about Writing Blogs” while the next says, “this paragraph is about Business Blogging.” Without them the document is reduced to a rant. It goes on and on without direction. You, the reader, can’t find anything. Looking at the document makes you negative. Not a good start!
Usability.gov touches on this point, “Once the information is chunked appropriately, write headings that are descriptive of the information. On the Web, page headings become links out of context on a previous page - like the table of contents of a printed booklet. Therefore, headings should clearly explain to users what page they are about to link to.”
Short informative headings help readers focus. They summarize text into ‘bite-size’ sentences. As the name implies a heading is the ‘head’ of the text you’re about to introduce.
Writing Effective Headings
Try to distill your headings into snappy 3-5 word sentences. Use positive language. Get to the point. Avoid using jargon, puns, archaic words, complex phrases, and other such affectations.
To write an effective heading:
-
Examine the section you want to summarize.
-
Identify the key topic. Every section (and paragraph) should have one key topic. Don’t mix ideas. You’ll confuse the reader and probably yourself in the process.
-
Write a single sentence that describes the section. Keep it very simple.
-
Revise the sentences and add an action verb.
For example, note the difference between Printing Duplex Reports, Saving XML Files To Shared Networks, Creating and Archiving Backups instead of Reports, Files, and Backups. While the former is informative and descriptive, the latter is dry and curt.
-
Emphasize actions with nouns. Write Printing Digital Forms rather than Printing.
Are Headlines Important?
Research from Eyetrack III shows that readers scan documents rather than read word by word, , especially when reading online. In general, readers start with the first heading (or summary) and then, if interested, scan the other headings on the page. If their interest is piqued, they’ll go back and read more text.
Eyetrack III add that “People typically scan down a list of headlines, and often don’t view entire headlines. If the first words engage them, they seem likely to read on. On average, a headline has less than a second of a site visitor’s attention.”
It’s not just the headlines that they scan, rather it’s the first few words in the headline that matter.
“For headlines — especially longer ones — it would appear that the first couple of words need to be real attention-grabbers if you want to capture eyes.”
Content is judged literally in the blink of an eye.
You can read more at: http://poynterextra.org/eyetrack2004/blurbs.htm
Checklist for Business Letters November 20, 2006
Posted by iawalsh in : How do I ?, Writing, Templates, Recommended, Tips , add a comment
Checklist for Business Letters
-
Be sympathetic to the reader’s situation. Acknowledge their frustration and any previous queries they may have made. Don’t rush into the letter without first mentioning any correspondence they’ve sent you or conversations you’ve had in relation to this business matter.
-
Include a short, positive introduction when opening your letter. Try to strike the right now from the start.
-
Use one idea for each paragraph. Don’t confuse the reader, or yourself, by mixing multiple ideas together. Prioritize the most important points.
-
Use headings to divide the letter into logical sections. This also makes it easier to scan. Most people read only the sections that interest them. Using headings to assist them in locating the relevant information.
-
Use white space to organize text. Avoid large, dense paragraphs. It’s very intimidating. No-one likes blocks of text. However, if used correctly, white space can emphasize the key sections in a document and give it more breathe.
-
Use bullet lists to identify key points. Use short sentences. Number items if action have to be performed in sequence. Avoid garish bullet points. Aim for a clean professional design.
-
Use tables to represent data. Strive to balance the ‘text to images’ ratio. Provide labels for each table. Consider using alternating stripes to add some color to the document.
-
Avoid using condescending language or adopting a patronizing manner. This will only infuriate the reader even more. Avoid using phrases such as, “As I’m sure you’re aware…” or “As you must know…” Always try to put yourself in the reader’s shoes.
-
Help the reader understand YOUR position. For example, why your product may have malfunctioned or how they can help you understand their situation more clearly.
-
Show your appreciation for the reader’s time, especially if they have already written to you.
-
Don’t refer to the reader as a ‘user’. It’s a horrible phrase. No-one wants to be called a user. In technical documentation, it may be acceptable but in business letters, avoid at all costs. Refer to them for what they are – a person.
-
Talk about the reader’s needs rather than your company’s products. Don’t harp on about your commitment to quality and so on. Get to the point. How can you fix their problem? How can you make their life better? Why should they ever buy your products again?
-
Avoid the passive voice. Use the active voice. It will give your letter more direction and help avoid ambiguity.
-
Vary the length of your sentences without disturbing your writing style, ie the rhythm of the letter.
-
Be succinct. Revise your letter and remove all extraneous information. A small word of warning, though. Don’t be too curt. It you perform too much surgery on your letter, you may inadvertently cut out its heart. Try to get a balance.
-
Read the letter aloud. Improve the writing until it sounds natural and easy on the ear.
-
Get another opinion! Ask a colleague to read your letter. Ask them the three things they dislike most about it. The third thing is usually what they really don’t like. The first two were the sugar-coating, but watch out for the third one…
-
Use positive language. The tone you adopt effects the reader’s response. Use positive words and phrases to stress the key points, while avoid a tendency to be over-zealous or excessively optimistic in your choice of words.
-
Cut out clichés. Review your document and remove all tacky, jaded phrases. Improve your writing by using more direct, clear communications. Clichés insult people and will not win you any favors with the reader. It smacks of laziness.
-
Make yourself available for further assistance. Include your email address, office phone number, and extension if possible. Don’t hide behind voice-mail or the secretary.
-
Provide a Call to Action so the reader knows what to do next.
Download 50 Indispensable Microsoft Word Tips November 17, 2006
Posted by iawalsh in : Cool Tricks , add a commentBNET offer these 50 tips as a free download in PDF.
As the site says “No matter how long you’ve been using Microsoft Word, you can always learn new techniques to help you work faster and smarter. Here are some of our favorite tips and tricks for Word 97/2000/2002(Office XP)/2003, organized into three sections:
I. The Basics
II. Advanced tips, and
III. Things you don’t have to do.
Get tips on recording Word macros, selecting noncontiguous text, and creating styles.
Get the PDF here: http://jobfunctions.bnet.com/download.aspx?&cid=113&docid=267101
What does structured editing mean? November 17, 2006
Posted by iawalsh in : Microsoft Office News , add a commentTerrific article from the MS Office team on structured editing:
“I know it often means different things to different people. So far, I’ve talked about what content controls are, and locking (which is a big part of structuring a document, as I use the term), but over this and the next post, I’m going to try to clarify what I mean by it, and how all of the parts of content controls fit together to make it easier/better in Word 2007.
In the first post, I showed the example of how you can literally type anywhere on the page. Cool – but if you’re creating a document where you don’t want the look to accidentally change, it’s also more than a little terrifying. Let me give you a real-life example:”
Jump over here to bring yourself up to speed on structed editing - and really impress your friends!