Archive for January, 2009

h1

Treat the writing process like the coding process

January 31, 2009

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!

h1

Word: Use StyleRef field to populate header/footer

January 30, 2009

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

    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

    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

    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

    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

    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

Raw field codes

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

h1

Explaining the various ‘bytes’

January 28, 2009

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.
Nesting dolls

Nesting Russian 'bit' dolls

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

h1

Avoid culturally specific references

January 27, 2009

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!

h1

Vista: Ownership details

January 26, 2009

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.
h1

Developing your business in a slow economy

January 25, 2009

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.

h1

Convert HTML and Word into Wiki markup

January 24, 2009

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.

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]