Treat the writing process like the coding process

Some time ago David H (Lone Writers SIG email discussion list) made this point about the processes of writing and coding (programming) and the time it takes for both. Here’s his take on it:

… I point out to the project manager that the programmers have had months to study the feasibility of the application, design the interface, build the engine, develop meaningful functionality, test the usability, and decide on the most efficient means of deployment. Then I add that the same considerations must be performed for the documentation, and that he can’t limit the documentation process to less than half the time of the coding process.

At least it plants the thought in the project manager’s mind that if he wants quality documentation, he’s got to treat the writing process like he treats the coding process.

I totally agree!

Word: Use StyleRef field to populate header/footer

Many corporate documents require you to have a table near the beginning of the document with details such as the author, the date created, a revision number etc. You may also be required to insert some of these details into the header and/or footer of the Word document.

While you can set up all sorts of macros, cross-references, document property fields etc. to do this, here’s a really quick solution using styles and the StyleRef field. This solution works in Word 2003, Word 2007 and Word 2010 at least. Before attempting this, you should know how to create a new style in your version of Word. Note: The StyleRef field will NOT ‘see’ any styles used in text boxes (see the comment from November 2017 below).

1. Create new styles for the text elements you want to capture. Give these styles names that are unique and are unlikely to be used anywhere else in the document (this is critical).  For example, DocAuthor, DocDate, DocTitle, DocRevNum. Don’t worry about formatting — the header/footer styles will control that.
   

   Create new styles

2. Fill in the details in the document information table (create a table if it doesn’t already exist).
3. Apply the relevant styles to each cell of the document information table — e.g. apply the DocTitle style to the cell containing the title.  DO NOT apply these styles anywhere else in the document — only one paragraph/cell in the entire document should have this style applied to it otherwise this solution won’t work.
   

   Apply the new styles to the relevant cells

4. Open the header or footer (Word 2003: View > Header and Footer; Word 2007/2010: Insert > Header > Blank then remove the control OR double-click in the header space to open the header).
5. Insert a StyleRef field for each of the elements you want to populate.  To insert a field: Word 2003: Insert > Field; Word 2007/2010: Insert > Quick Parts > Field. Select StyleRef from the list of field names on the left (1), then select the style (e.g. DocAuthor) from the list of style names on the right (2), and click OK (3).
   

   StyleRef field

6. Repeat step 5 for the other StyleRef fields you want to add. Add words, spaces, punctuation etc. between the fields, as required.
   

   Header created from the styles

7. Voila! Instant header/footer populated with the document details. And even better — as soon as you update any of the data in the cells, the header/footer automatically updates too.
   

   Instant update

If you want to see what’s going on behind the scenes, you can always toggle the field codes in the header/footer to see how it works:

Raw field codes

(Thanks to Ken E on the STC Lone Writers discussion list who shared this technique with us.)

Explaining the various ‘bytes’

Do people you know get confused with the relative sizes of the ‘byte’ words — kilobyte (KB) megabyte (MB), gigabyte (GB) etc.? My husband does and often asks me to tell him — again — which is bigger. Here’s a solution — nesting Russian dolls in ‘bit’ size order! Now you just look at the dolls to understand that a kilobyte is smaller than a megabyte.

You can get these dolls (in black or white) from here:
http://www.artlebedev.com/everything/matryoshkus/blanco/

Avoid culturally specific references

One of the tenets of good technical communication is to avoid culturally specific references, especially if your material is to be translated into other languages. But what’s a culturally specific reference? In simple terms, it’s a word or phrase that has meaning for members of a cultural group, but has limited meaning, no meaning, or some other meaning for people outside that group.

Culturally specific terms are typically those commonly known within one country but not another. Within a country, it can refer to terms known to one region but not another, or words spoken by different ‘tribes’ (e.g. differences in terms used in generational groups, industry groups, ethnic groups, etc.).

Some culturally specific terms are easy to identify — names of foods and beverages, for example (pop, soda, coke, soft drink…). But other times they’re not so easy, especially if you don’t even realize that the term or phrase might not be known by others. Time spent visiting and living in various parts of the world helps in understanding such differences, but is only a start. The best way to identify culturally specific terms is to get someone from outside the expected audience demographic to read your material — look for people from different age groups (if generational language may be important); from different regions, states, countries; from different educational levels; from different ‘tribes’.

Sometimes what appears to be a common term to you, is not so common to others or in other contexts.

An example of a culturally specific term that I encountered in someone’s email to a global audience was ‘water cooler’. The context was using it in a mission statement — “To provide a virtual water cooler for an international community of [occupation] …, where they can share ideas, solutions, technology, professional support, and encouragement.”

My response to that suggestion was:

I believe that ‘water cooler’ is fairly US-centric as a term. It’s not commonly used in Australia, for example (I can’t speak for the rest of the world, obviously), though it’s gaining currency as we take to bottled and filtered water more and more — and as Dilbert and friends reach a wider audience. While many offices and homes now use such things, most would still use tap water.

I can recall visiting the US for the first time in 1985 and being amazed (and quite horrified) that friends had these large water bottles and coolers in their own homes. For me, drinking water had always come out of a tap and I couldn’t understand why you would get your drinking water any other way. For much of the developed world, that’s how it still comes — and for other parts of the world, it might be the village pump (which I guess is a very early version of a ‘water cooler’ community).

So, much as I personally like — and relate to — the term, I’d be interested to hear how others respond to a term that may be specific to either a geographic region or to a particular socioeconomic class.

One technique I use to check terms I’m not sure that a US audience would be familiar with is to have a ‘buddy’ in the US — a friend I can email or ping (‘send an instant message’) with really quick questions about language I *think* may be culturally specific (hi Char!).

Find yourself a buddy — they’re an invaluable resource!

Vista: Ownership details

Did you buy a new Vista computer from a major manufacturer or supplier? Then it’s likely that the registered organization is still listed as Dell, Hewlett-Packard, etc. And your name may not be listed as the registered owner either.

You have to change a registry setting to put your own name and organization into Vista — this means you’ll probably need administrator rights to your computer.

1. Click the Vista start button.
2. Click Run (in the right panel).
3. Type regedit then press Enter.
4. If User Account Control is turned on, you’ll be asked for permission to continue — click Continue.
5. Go to HKEY_LOCAL_MACHINE > SOFTWARE > Microsoft > Windows NT then click on CurrentVersion.
6. Check the names listed in the Data column for RegisteredOrganization and RegisteredOwner.
7. If you need to change either of these, right-click on the item and select Modify.
8. Enter the correct details in the Value data field, then click OK.
9. Repeat for the other if it needs to be modified too.
10. Close the Registry Editor window.

Developing your business in a slow economy

I was deleting some old emails when I came across this one from a Tom White on the STC Contractors and Independent Consultants SIG. It was dated July 2001 but I think the advice is as relevant today as it was then.

Unfortunately, I can’t acknowledge Tom properly as I can no longer find The Independent Beacon, the newsletter where this information was first published.

Tom’s email from 2001 said:

A few weeks back I asked the group for ideas on how to weather the current economic slowdown. We got a lot of really good ideas from this group. We’ve synthesized all these strategies in our newsletter, The Independent Beacon…

A special acknowledgement goes to Jean Richardson, Ann MacKenzie, Linda Gallagher, Melody Brumis, Audrey Choden, and Cathy Moore for your insights and advice.

To summarize, there are six areas you can address:

* FLEXIBILITY
Consider doing other kinds of work that might be in-demand, working for clients in other locales or industries where the economy may be more robust. Be creative in representing your skills and services.

* CLIENT LOYALTY
Stick with your anchor clients through thick and thin. Be there to find out what they really need, when they need it. Adapt accordingly. Make sure you offer support in ways they can accommodate paying you.

* ALTERNATE COMPENSATION
Try to get paid in different ways, such as under alternate budgets, deferred payments, equity, services exchanges, and other creative ways that get around frozen budgets.

* PRODUCTIVE USE OF DOWN TIME
If you foresee some slack time coming, take classes to improve your skills, work on your Web site and marketing, or do other work–even if non-billable–that will enhance your business and value to future clients.

* NETWORKING
This is an especially important time to renew and cultivate your network.

* RESTRUCTURING
Many independents have found that in unity, there is strength. By aligning yourself with other independents with complementary skills, you may be able to bid projects you might not otherwise have access to.

Convert HTML and Word into Wiki markup

Thanks to some members of a technical writing list I’m on, I found out about some tools that convert HTML and Word to Wiki markup. I haven’t tried any of these yet, so I don’t know how ‘clean’ the end result is, but I offer them as possibilities if you’re looking for ways to do this.

• http://www.mediawiki.org/wiki/Word_macros (Word macros to MediaWiki)
• http://www.infpro.com/Word2MediaWiki.aspx (one of the Word macros mentioned in the link above)
• http://search.cpan.org/~diberri/HTML-WikiConverter-0.63/lib/HTML/WikiConverter.pm (HTML converter to various Wiki markups)
• http://goessner.net/articles/wiky/ (Wiky: A bidirectional markup converter — Wiki to HTML and HTML to Wiki)

Please add any other tools you’ve found via the Comments.

(Thanks to Wade C, Bill S, and Kathy T for these suggestions)

[Links last checked January 2010]

Word: Change the spaces after a period

Here was my problem as I described it to the Microsoft Office Discussion Group:

I have a long document that several authors have worked on. Some use two spaces after the period, some one. The corporate style is two (not my decision!), so I’m trying to figure out an easy way of finding ALL instances of only one space after a period and replacing it with two spaces. Sounds easy? Nope.

Problem is that each sentence following the space starts with a different letter. I want to be able to find “.<space>[A-Z]” and replace with “.<space><space>[A-Z]” where [A-Z] is any capital letter. The original letter must be replaced with itself.

I can do this one letter at a time (e.g. “.<space>A” replace with “.<space><space>A” but as I know there will be many documents like this, I’d like to know if there’s a simple way to automate the process, either using wildcards, special characters, or a macro.

Oh, and adding a minor complication to this — I don’t want to do a ‘Replace All’ as some legitimate periods are followed correctly by a single space (for example, in the list of References, or after “i.e.” or “e.g.”).

Does anyone have any idea as to how I can achieve this? I’m happy to click Replace for each instance found, but I really don’t want to set up 26 different find/replace sequences to hit all letters of the alphabet.

Within two hours I had two responses, both of which offered a different method to achieve what I wanted. I tested them and both solutions work well.

Brian’s solution

Try Find ‘period space space’ and replace with ‘period space’ to get them all the same, then find ‘period space’ and replace with ‘period space space’.

You can then search on ‘i.spacespace e.space space’ and replace with ‘i.e.space’. Do the same for e.g.

Graham’s solution

With the wildcard option set Find what to (.) ([A-Z]) and Replace with \1  \2

(NOTE: There are TWO spaces between \1 and \2.)

Watch out…

There are a few things to watch out for.

• If you have a list of references written like Smith, JA. 2010. two spaces will get added after the A. and the 2010. To avoid this, select only the sections of the document you want to check and don’t select your References list.
• If you have citations written like (Smith. 2010), two spaces will get added after Smith.
• Abbreviations with periods like e.g., i.e., and etc. will all get changed. You’ll need to run a separate find/replace to change them back.

Update 18 February 2009: I have now used Graham’s solution many times over — and it has saved me hours of work. It’s a winner!

Update 31 July 2009: Seems the latest APA Publication Manual is now recommending two spaces after a period, even in HTML pages (which will require the use of the non-breaking space [ ]). Some details here: http://spacewaste.wordpress.com/

Dealing with large documents

Late last year I attended the ASTC (NSW) annual conference, where Helen Lewis spoke about the revised edition of a book she co-authored with Hilary Hudson: The Don’t Panic guide to annual report production.

I was very impressed with Helen’s presentation — enough to buy the book! It’s very good. While the authors’ focus and point of reference is producing annual reports for large government departments, the advice they offer applies to ANY large document or report for ANY organization. They cover all the bases from estimating time and project planning, to working with printers, editors, indexers, multiple writers, etc.

It’s only a short book (less than 100 pages), very easy to read, and packed full of essential information. It’s a worthy addition to any writer’s library.

You can buy a copy for AU$27.50 direct from the book’s website: http://www.annualreporter.com/

The Don't Panic Guide to annual report production

Word: Run Format Painter with the keyboard

One of Word’s handy tools is Format Painter, which is the paintbrush icon in all versions of Word; in Word 365 for Windows it’s on the Home tab > Clipboard group. It’s a tool I use often, but sometimes it’s a nuisance to continually click in the text that has the formatting I want to copy, move the pointer to the top of the window to click the icon, then move it back down to click in some other text to apply the same formatting, repeat…

But did you know there’s a keyboard shortcut for Format Painter?

1. Click in the text with the formatting you want to apply.
2. Press Ctrl+Shift+C to copy the formatting (make sure you include the Shift as Ctrl+C only copies the text).
3. Click in the text to which you want to apply the formatting.
4. Press Crtl+Shift+V. You can press this key combination as many times as you like while the document is open — it retains the copied formatting until you do step 2 again.