Writing Labs

Writing Narratives

The trick to writing effective narrative is to remember the following mantra: “Less is more.” Your goal as a technical writer is to trim the fat and leave the steak. I’ve included a couple of exercises that will help you learn the process of removing information that is not necessary.

Remember that you’re trying to introduce a concept without going into too much detail. If the learner needs more information, the learner can always refer to the user manual. The narrative should be short and concise, and get quickly to the point.

Consider the concept of making a word appear in a bold style: Just about every program I can think of lets you make text bold. If you had to write a narrative introducing the bold feature, you could include the history of bold, why bold is important, the many ways you could make a word bold, testimonials on the power of bold and examples of how bold makes things, well, bold.

If you were to write all that, you would lose the point of the narrative.

Remember that your goal is to introduce a concept quickly and in a concise manner. If I was going to introduce bold, I’d write why bold was important and show a few ways you can make text bold. And that’s all.

Here's an example: You have been asked to write a narrative that introduces the concept of Absolute and how they relate to Relative formulas (both formulas are common features in spreadsheet applications such as Microsoft Excel). Hold on to your hats, because here's the text you were given by the subject matter expert (SME).

Note: For this example, it is assumed that users know all about Relative formulas.

Dear Technical Writer:

Here are the differences between relative and absolute references you asked for. Sure hope this helps ya!!!!!

Relative references: Well, relative cell references are kinda fun. They are the most commonly used references in a formula. So, WOW! Anyway, as you know, when you create a formula, references to cells are usually based on their position relative to the cell that contains the formula. Have I lost you? Here’s an example: cell B6 contains the formula =A5; our product finds the value one cell above and one cell to the left of B6. BAM! This is known as a relative reference.

Got it? OK. So, when you copy a formula that uses relative references, our product automatically adjusts the references in the pasted formula to refer to different cells relative to the position of the formula. Is that a good thing or a bad thing? Depends on what you ate for lunch! Har de har har!!!! Here’ another example: maybe you’ve got this formula in cell B6, =A5, which is one cell above and to the left of B6, has been copied to cell B7. Our product has adjusted the formula in cell B7 to =A6, which refers to the cell that is one cell above and to the left of cell B7.

Absolute references: But suppose you don't want to adjust references when you copy a formula to a different cell. You might be hosed… unless you use an absolute reference. If the formula multiplies cell A5 with cell C1 (=A5*C1) and you copy the formula to another cell, our product will adjust both references. That could be BAD BAD BAD!!! You can create an absolute reference to cell C1 by placing a dollar sign ($) before the parts of the reference that do not change. To create an absolute reference to cell C1, for example, add dollar signs to the formula as follows:=A5*$C$1 You are getting this aren’t ya?

Switching between relative and absolute references: I know you must be wondering about this. What if you created a formula and want to change relative references to absolute (or vice versa), Well, first select the cell that contains the formula. Then in the formula bar, select the reference you want to change and then press F4. Each time you press F4, our product toggles through the combinations: absolute column and absolute row (for example, $C$1); relative column and absolute row (C$1); absolute column and relative row ($C1); and relative column and relative row (C1). For example, if you select the address $A$1 in a formula and press F4, the reference becomes A$1. Press F4 again and the reference becomes $A1, and so on.

Again, I hope this helps!

There is nothing easy about writing good narratives. What you’ll typically get from subject matter experts is all kinds of unnecessary information and possible “techno jargon” that won’t do your readers any good.

What you’ve got to do is eliminate all of the unnecessary information. Remember that you’re trying to also keep the narrative short if possible. Your readers can always refer to the user manual if they want in-depth information.

To begin with, the first few paragraphs can be removed right away. They discuss relative formulas. The information is good background information for you, but not necessary in the narrative about absolute cell references.

And here's one possible solution:

Relative cell references are the most commonly used references in a formula. However, there will be occasions when you will not want the formula to change when you move or copy it to another cell. In this case, you will want to use an Absolute cell reference. Unlike Relative cell references, which do change, an Absolute cell reference does not change when you move or copy it to other cells.

Challenge Exercise

Sometimes in technical writing, it is not necessary to rewrite provided information. Instead, you may just need to restructure the information and do some minor rewrites.

Your goal during this challenge is to introduce Cascading Style Sheets. On a separate sheet of paper, reorganize the information below and weed out the unnecessary text.

Dear Technical Writer:

Here is the information about Cascading Style Sheets you asked for.
Style sheets will allow web page developers to combine several font and page formats into easy-to-assign commands. The beauty of a style sheet is that once you’ve assigned a style sheet, you can edit the style and make thousands of changes to hundreds of web pages in minutes.

First off, we’ve got three different styles that people can use... Linked, Embedded and Inline. The differences? With Linked styles, the attributes are stored in a .CSS file that is not a direct part of any HTML file. Very nice. Embedded styles are kept directly inside files and they override Linked styles. Inline styles are when you directly format text (like making a word bold). Inline styles are the most powerful style (I didn’t say the best, I said the most powerful... I think Linked styles are the best). If you apply a paragraph style to a paragraph that also has Inline styles, the Inline styles won’t go away. That might get a bit frustrating.

Anyway, there’s a very good reason to use style sheets. If a site is going to contain a bunch of text formatting such as hundreds of <h1> tags, <h2> tags and a lot of <p> tags. it’d take a bunch of work to format all the text manually. Not convinced? Here’s some math to put things into perspective: If you’ve got 50 headlines that need to be formatted and you want to make every headline Arial, Bold, 14 pixels, Centered. That’s four commands per headline, multiplied by 50. That equals 200 commands you must enter to format all of the headlines. And you haven’t even started the subheads. But say you’re adventurous and you manually format everything. And you don’t use styles. When you finally finish the site and send the finished site around for approval, you know what’s going to happen. Someone isn’t going to like the fonts, someone else won’t be crazy about the color and so on and so on. It’s now going to take an eternity to make changes. Bummer. Best to use styles.

Let me know if you have any other questions.

Possible Solution