Tips Archive

I've tried to organize these tips a bit to make it easier to find information of use to you. Click a link below to find one or more tips about that topic.

Please note that these tips were started in 1998 and all outside links worked at the time of the original writing. Because Web sites come and go, some links may no longer work.

E-mail/Microsoft Outlook 

FrameMaker

Microsoft Word

Online help

PDF files

Working as an independent

Writing tips

E-mail/Microsoft Outlook

Novice Tip

As an independent technical communicator, one of the biggest challenges I face is maintaining the performance efficiency of my computer. Receiving and sending large amounts of e-mail can slow your system down, if you don't do periodic maintenance of your e-mail file.

I've had Microsoft Outlook lock up my computer because of the size of the files it creates.  You can avoid this problem by periodically archiving old e-mail messages, both sent and received, or any other old information within your Outlook folders (calendar, tasks, etc.).

Here are the basic steps to perform the archiving process (Outlook 2000):

To archive MS Outlook data:

1. From the File menu, select Archive.
   
   
2. Select the Archive this folder and all subfolders radio button.
   
   
3. From the Archive items older than drop-down list, select a date.
   
   

• The data older than the date you select (within the selected folder and subfolders) will be archived.

4. Using the Browse button, select the path and name of your archive file (archive.pst).
   
   

• Note the location of the archive file. You may need to access this information again.

5. Click OK.
   
   

• Outlook archives the data you selected. You can track the progress of this process in the lower-right corner of the window.

• You can open the archive file by selecting File | Open | Personal Folders File(.pst) and navigating to the archive file.

Novice Tip

E-mail is a vital tool today. I use it extensively to communicate with my clients. Some tips for your messages:

• Break up your message into paragraphs just as you would anything you write. Long, unbroken blocks of text are especially hard to read on your computer monitor.
  
  
• Use dashes or some other symbol to mark the beginning of bullet points in your message. You can't be sure that your recipients will recieve formatted text that has real bullets in it, but using plain old dashes or asterisks (as below), helps to break up text.

- This is an example of a "bullet point" in an e-mail message. It may not be as pretty a real bullets that you can use in Word or other word processors, but it still helps to mark the beginning of a new point.

• Always include your full name and e-mail address at the end of the message. I often see messages posted to lists that have no name or just a first name. Everyone on an e-mail list cannot know each list member. Use your software's signature function to automatically create a full signature. Just try to keep it no longer than 3 or 4 lines.

Advanced Tip

I know that there are many different e-mail client software products out there, but many people use Outlook and so do I.

Do you ever want to know someone's e-mail address so you can give it to someone else, include in a message, or just jot it down? When you receive a message from someone, right-click the sender's name in the From field at the top of the message, then click Properties. You'll see the sender's name and e-mail address.

To go a step further, you can add the person to your Outlook address book automatically by selecting Add to Contacts or Add to Personal Address Book.

FrameMaker

Novice Tip

You may be using FrameMaker to document a family of products and find that some information, like a glossary, is common across books. To save yourself from having multiple copies of the glossary information, see if you can create one glossary for all products and then share the file.

In FrameMaker, there are two ways to share a file:

• Using text insets (importing a FrameMaker file by reference)
• Adding the same file into each book

Either way, whenever you update the text in the one source file for the glossary, it gets updated everywhere the text inset or file appears. It's a great way to save time and avoid errors when updating reused content.

These methods work best when the content is identical across all books that you need to create. For some ideas about how to handle situations where some content within a file is the same and other content is different, read the Advanced Tip.

Advanced Tip

When you find that you need to document products that are very similar, but need to create different books for each, consider using FrameMaker's conditional text. This tool is a very powerful way to handle multiple versions of a product or multiple products in a single book. 

Using this feature can also be challenging. Here are a few ideas for planning your use of conditional text. Future tips will feature ideas about implementing it.

Conditional text planning issues:

• Plan before you start using conditional text to ensure a successful implementation.
  
  
• Consider the full product line and all of your conditional text needs: where might you use variables, text insets, or unique files to avoid complex tagging of text.
  
  
• Consider what content is alike across products: it should probably be at least 30% the same for the conditional text to work well.
  
  
• Consider what content is different across products: if it's more than 70% different, you might want to think about whether using conditional text makes sense (these numbers are just guidelines, not rules).
  
  
• Determine the best way to structure book files: consider whether some files should be unique such as specifications and installation of different models with different form factors.
  
  
• Decide the best place to store imported graphics: in one common folder or in separate folders by product (consider whether files will be moved to different locations and lose their links).

Advanced Tip

FrameMaker's conditional text is a very powerful way to handle multiple versions of a product in a single document. Using this feature can also be challenging. Here's a problem that I ran into recently and the solution.

Problem

The problem comes in when I go to print. After you make a row in a table conditional, the text in the row stays black, but the background of the row (sort of an outline around the text) gets the conditional color. I've figured out how to get the colored text to be black (Spot Color as Black/White in the Print dialog), but I keep getting this black background around the table rows when I print. How do I print without getting this?

Solution

If you go to the conditional text Show/Hide dialog box, there is a check box that allows you to show or hide the conditional markers. Deselecting this (then clicking Set) will make all the conditional markers (like colors, underlining, the outline in the table cells, etc.) go away. When you are done printing, you can show the conditional markers again for writing and editing. (Solution provided by Liza Metzger.)

Advanced Tip

Here are two FrameMaker tips that I learned the hard way. Another writer and I could not figure out why chapters in a project were not autonumbering properly. Everything seemed to be set up just fine. (I'll go over how to set this up in a future tip.) We learned about two things that can cause this problem.

First, the paragraph that you use for the chapter autonumbering must be on a body page, not a master page. If it is on a master page, the numbers don't update as they should to give you sequential numbering of your chapters.

Second, to get the chapter numbers to update properly be sure to select Autoconnect under Format/Customize Layout/Customize Text Frame below the Flow Tag option. Do this in every file. I did not find this anywhere in the documentation

Novice Tip

I find that a lot of clients initially talk to me about writing a manual, meaning a hard-copy book. As I learn more about my clients' products, I often find that they also need online help for the software.

In these situations, I offer a single-sourcing solution that lets me create the print and online content at the same time using the same source files. Some technical communicators may not agree with this approach, but for many small companies, there is no feasible alternative. I find, in fact, that single-sourcing can work very well for most of my clients.

Here are a few tips related to single-sourcing:

• Plan for the print and online needs by thinking about the information that you want to include in each medium.
  
  
• If you are using a tool like FrameMaker, design your template to include conditional tags for PrintOnly and OnlineOnly.
  
  
• Decide whether to include screen shots and other graphics in the online version. Sometimes the screen shots are not needed if users are already in the application when they invoke the help.
  
  
• Think about how to handle references to other parts of your content. Do you want to refer to another "chapter," "section," "topic," or just use the section title.

Single-sourcing takes some planning and some time to get used to, but it can let you reuse much of the content you write and save you time. See the advanced tip below for more information about using conditional text in FrameMaker.

Advanced Tip

Once you've done some planning for the conditional text tags that you'll need in FrameMaker, you are ready to create the tags. 

Creating the tags is not difficult if you've thought through your needs, and you can always go back and create new tags as necessary.

Here are some things to think about when creating conditional text tags:

• Give the tags names that convey their purpose, for example, OnlineOnly, PrintOnly, or ProductA.
  
  
• Make sure that the colors you use for each tag are both legible on your monitor and distinguishable from each other (and from black).
  
  
• Create your tags in your template and then import them into all book files. Be sure to import your colors, too, if you created any new colors for the tags.
  

Novice Tip

In FrameMaker, sometimes you need to rename a paragraph style. You can do this and have FrameMaker rename each occurrence in the of the style in the file. It does not, however, change each occurrence in the book file automatically. You'll need to repeat the procedure below in each file.

If you have to make this type of style name change to many styles throughout one or more books, you might consider using FrameScript (http://www.framescript.com/) and purchasing scripts that can do this (and much more) in whole FrameMaker books (http://members.shaw.ca/philip.sharman/FrameScript.htm).

To rename all occurrences of a paragraph style:

1. Create the new paragraph tag.
   
   
2. Click in a paragraph with the old tag.
   
   
3. Open the Style Designer (Ctrl+m).
   
   
4. From the Paragraph Tag drop-down list, select the new paragraph tag you want to apply.
   
   
5. From the Commands drop-down list, select Global Update Options.
   
   
6. Select All Properties.
   
   
7. From the All Tagged drop-down list (bottom of the dialog box), select the old paragraph tag.
   
   
8. Click Update.

• A message displays: OK to change all [old tag] to [new tag]?

9. Click OK.

Advanced Tip

Conditional text in FrameMaker is very powerful. See the tips archive page for some planning and implementation ideas. One thing that you cannot do automatically is have a specific paragraph style always use a specific condition. However, you can use the search function to apply a condition to each occurrence of a specific paragraph style. 

To apply a condition to all occurrences of a style:

1. Apply a unique paragraph tag to all of the text to be conditionalized.
   
   
2. In one instance, manually apply the condition.
   
   
3. While still selected, use Edit>Copy Special to copy the Conditional Text Settings.
   
   
4. Set up Find/Change to find the special paragraph tag by name and to change By Pasting, which will apply the copied condition without otherwise changing the text.

Microsoft Word

Advanced Tip

Does it seem like you never have enough time? Do you use Microsoft Word a lot? If you answered yes to both of these questions, I have a tip for you.

Use macros! I sometimes forget about using macros, but they are a great way to save time for repetitive tasks. If you are really advanced, you can create all sorts of macros that do all kinds of great things for you.

I tend to create simple ones that save me time when I need to apply formatting to a lot of graphics or change a paragraph format on a bunch of headings, but I don't want to change the style.

Rather than repeating how to do it here, check Word's online help. In Word 7.0 (Office 95), the instructions are good. Go to the Index tab and search for macros, then recording. Follow the steps for recording macros and save yourself some time!

Advanced Tip

Here is a tip to help create single table of contents (TOC) from multiple Word files.

To create a TOC from multiple Word files:

1. Create Word files with headings to be in the TOC.
   
   
2. Create a separate file for the TOC.
   
   
3. In the TOC file, insert a TOC field code. (Insert/Field; select Index and Tables; select TOC.)
   
   
4. Then insert an RD code. (Same steps as #3 above, except select RD as the last step.)
   
   
5. Inside the right bracket, enter the name of the file for which you want to create the TOC.
   
   
6. Repeat steps 4 and 5 for each file.
   
   
7. Attach the TOC file to the template used for the text files.
   
   
8. In the TOC file use Insert/Index and Tables to select which styles to include in the TOC.
   
   
9. Click in the TOC field and press F9. Word generates the TOC.
   
   
10. Adjust the TOC styles in the TOC file as needed and save to the template.
    
    
11. Update the TOC by opening the TOC file, clicking the TOC (it turns gray), and pressing F9.

Online Help

Advanced Tip

Have you ever tried to place a table in a Windows help file using Doc-To-Help or ForeHelp (and probably RoboHelp)? Gridlines, borders, shading, and merged or split cells can be a problem.

One way to solve this problem is to convert the table into a graphic. However, you lose editing capabilities when doing this. To get around this problem, turn the table into an embedded MS Word OLE object (a Word document within a Word document). This lets you go back and edit your table.

Here are the steps you need to follow:

1. Create your table in Word.
   
   
2. In your .doc file, select Table | Select Table.
   
   
3. Select Edit | Copy.
   
   
4. Click a new location in the .doc file.
   
   
5. Select Edit | Paste Special.
   
   
6. Select As: Microsoft Word Document Object.
   
   
7. Click OK.

• The table is now embedded in your document, but is treated as a graphic by the make into help process. (This applies to Doc-To-Help and most likely to RoboHelp also.)

8. Double-click the table to edit it and fix any formatting problems.
   
   
9. Make your edits.
   
   
10. Select File | Save.
    
    
11. Select File | Close.

You now have a graphical representation of your table, formatted the way it is to appear in your help file. You are ready to copy it into your ForeHelp file. If you have not achieved the results you want, repeat steps 8 through 11.

This tip has been adapted from the WEXTECH  Newsletter, Winter 1996-97, Vol. V No. 1, Tips and Techniques, pg. 2.

Advanced Tip

Do you wonder if there is a resource out there to help you with Windows help file problems? A couple of resources exist. You can subscribe to the winhelp-l e-mail list, but if you want to find information and don't want to subscribe to yet another list try this URL:

www.documentation.com

This site contains archives of the winhelp-l list (and other lists) that you can search.

PDF files

Novice Tip

The portable document format (PDF) that you create using Adobe Acrobat is becoming a very popular format for documents. We find that clients want PDF files for review drafts and final output for a printing company.

Why is PDF becoming so popular? Well, I don't claim to have all the answers, but one key factor is its portability. Anyone using any computing platform can download the free Acrobat Reader software and read any PDF document. PDF documents are also compressed, making them much smaller than the document would be in its native format. And, it is getting easier to create PDF documents from MS Word, FrameMaker, and other software tools.

Creating a PDF may be easy, but troubleshooting problems with PDF files is not so easy. See the Advanced Tip below for information about creating PDF files.

Advanced Tip

Continuing with the topic of PDF files, I'd first like to say that I am not an expert. I've learned a lot by trial and error and from advice from colleagues, but I'm still not quite sure how to make PDF files work every time. If you have additional PDF tips, please share them with us. We'll post them here to help others.

The following tips are not in any particular order, but are some key things that I've learned:

• If you print a PDF file to a nonpostscript printer, graphics and sometimes text are likely to print improperly. I'm purposely vague here because improperly may be anything from fuzzy graphics to text that is just a gray blur. Using a postscript printer usually prints the file properly.
  
  
• If you are using Acrobat 4.0, be careful about the settings you use.
  
  
  • If you are creating a PDF to send to reviewers or to post on a web site, you probably want to use the job option that comes with 4.0 called ScreenOptimized. This ensures that the resulting PDF file will be compatible with Acrobat 3.0 Reader, which is what most people have. The new 4.0 Reader is available from Adobe, but don't count on most people having it.
    
    
  • If you are creating a PDF for final printing, contact your printer to find out what driver and job options the printer recommends. Then be sure to get a proof from the printer to ensure that the document's quality is what you expect.
    
• Be prepared to try different postscript printer drivers and different job options until your PDF file works properly. Be sure to look at the PDF file after you create it and look for missing characters, missing graphics, fuzzy graphics, etc.
  
  
• Go to the Adobe web site (http://www.adobe.com) and search the support section of the site for assistance with PDF file issues. I found more information about version 3.0x than 4.0, but that will likely change over time.

Working as an Independent

Novice Tip

As an independent technical communicator, one of the biggest challenges I face is how to know everything I need to know. With technology changing so rapidly, software companies constantly coming out with new versions, and the now nearly infinite varieties of online help formats, how do you keep up with it all?

It certainly is a challenge, and of course, no one can know it all, but there are many resources available to you. I'll discuss some of the resources here and additional resources in the Advanced Tip section below:

• I strongly recommend that you join your local Society for Technical Communication (STC) chapter (http://www.stc.org) and make sure that you are on the chapter's e-mail list. (Most chapters have one.) Your fellow technical writers are a valuable source of information. Post your questions to the list and you'll be amazed at the responses you receive. Of course, you should try to respond to other members' postings whenever you can, too.
  
  
• Other organizations that you belong to may also have e-mail lists. For example, in the Denver-Boulder metro area, you can join the Boulder Writers Alliance (BWA) (http://www.bwa.org). BWA also has an e-mail list and I often post my questions to both the STC and BWA lists.

Advanced Tip

Continuing with what I'll call here "self-help resources for independents," you'll find many more e-mail list resources listed below. Please note that e-mail lists come, go, and change their addresses. The address below may or may not still exist.

Generally, to subscribe send a message to the Listserv address. In the message body enter:

subscribe [list name] [your name]

For more mailing lists, go to: http://www.prc.dk/user-friendly-manuals/ufm/maillist.htm

Novice Tip

As a successful independent technical communicator, I am often asked about how I got started, how I run my business, how I find clients, how I use my marketing materials, and many more. I'll answer a couple of these briefly here.

How did I get started?

Well, part of that was easy. I was downsized from large company, so I had to do something! Before that fateful day, I had figured out, after much soul-searching, that technical writing would be a fit for me. After the downsizing, I immediately joined STC (Society for Technical Communication www.stc.org or www.stcrmc.org) and started reading books about writing, technical writing, starting a business, being a consultant. A few of my favorite "novice" writing books are on my book list. You might also want to read my article series.

Luckily, I landed a couple of contracts that gave me experience with software documentation, online help, and training materials. With that experience, I was able find more work. I continued to attend STC meetings, workshops, the STC Annual Conference, and anything else where I could learn more. My education continues today with similar activities.

How do I find clients?

Much of my work comes from leads from other STC and BWA (Boulder Writers Alliance www.bwa.org) members. Being active and visible in organizations is the best way I have found to find work. I don't mean just going to meetings. I mean volunteering and doing good work for the organization. Being reliable in your volunteer tasks is critical to your efforts. This gets you known and known in a positive way as someone who gets things done. Check some of the information and resources in the Freelance FAQ (www.stcrmc.org/freefaq.htm).

Advanced Tip

Continuing with the topic of being an independent technical communicator, I'll share a little about handling projects. I find that to keep busy, we have to have more than one project to work on at a time. Invariably, every project has down time while product development is continuing, while your subject matter expert (SME) finds time to answer questions, while SMEs review drafts, etc.

Juggling a few projects can be tricky. You must be sure that you can meet your commitments. We pride ourselves on always doing so. You also have to find ways to maintain your sanity and have some fun. We make sure that we do that, too.  We are careful about due dates and make sure that they are reasonable based on what we know about the project and our other work. This is seldom a problem.

Be sure that you never blame your workload for a missed deadline or being behind. That's bad form. I'm open with my clients about having more than one project, but I try not to get into a lot of detail about my other work.

Novice Tip

It's almost tax time. If you are an independent, you still have time to reduce your 1998 tax bill. You can still make contributions to your IRA, SEP, or Keogh retirement accounts for 1998. Any contributions you make, reduce your taxable income and help you prepare for retirement. Talk with your accountant, investment advisor, or tax advisor about setting up these accounts and which is best for you.

Advanced Tip

Staying with taxes and related topics. If you are an independent and work on a 1099 basis, that is, you are not an employee of a contracting firm, you should become knowledgeable about which expenses are deductible and which are not. These rules vary for some expenses based on the form of business you have set up: sole proprietorship, partnership, corporation (there are several types of corporations).

For example, if you pay for your own health insurance, corporations can deduct the full cost. Sole proprietors and partnerships can only deduct 40%. This percentage is set to go up over time and eventually reach 100%.

You can learn more from your accountant, from IRS Publication 334 - Tax Guide for Small Business, and from IRS Publication 17 - Your Federal Income Tax for Individuals.

You can also access valuable information from the IRS web site:

For information about starting a small business, check: http://www.irs.ustreas.gov/basic/bus_info/sm_bus/pre-start.html

For information after you are operaing your business, check: http://www.irs.ustreas.gov/basic/bus_info/sm_bus/operating.html

Writing tips

Novice Tip

To write effectively as a technical communicator, you need to get to the point. This is not the time to impress! Clarity and being concise are two key elements of successful technical communication.

To achieve clarity, the document must present a single meaning to the reader. There is no room for uncertainty or mutiple meanings in a technical communication document.

Be concise! Do not add words unless they add meaning. Remember, your goal is to inform without confusion and in the shortest time possible. Get to the point! Your readers are very busy people.

To be clear and consice:

• Use words that convey the most precise meaning.
  
  
• Use language that is appropriate for your audience.
  
  
• Be concise. Make the document just long enough to be clear.
  
  
• Do not try to impress. Using unnecessary or high brow words and phrases detracts from the document.
  
  
• Have your document reviewed by readers at both the high and low ends of your audience.
  

Novice Tip

As someone new to technical communication, you may find that you have some old habits that are hard to break. Even more experienced writers sometimes need to refresh their memories about good technical writing.

Good technical writing must be clear and accurate. That's a given. But, how do you make it accessible, easy to read, and easy to understand? One method that helps is to "chunk" information. Chunking means breaking down tasks and information into small, "bite-sized" pieces that readers can easily digest.

How to chunk? Well, there are lots of ways. Here are a few:

• Write short sentences.
  
• Keep paragraphs short.
  
• Use lots of headings to break up information into logical groupings by task.
  
• For online information, limit topics to one or two screens whenever possible.
  

Novice Tip

You may find that you have some old habits that are hard to break. Even more experienced writers sometimes need to refresh their memories about good technical writing.

"How do you write such short sentences?" a client asked me recently. He admired my ability to keep sentences short, concise, and clear. I do it by editing, a very important phase in all types of writing.

When you edit:

• Look for long phrases that you can replace with short ones.
  
• Eliminate unnecessary words and phrases.
  
• Use short, common words rather than long, fancy ones.
  
• If a sentence is more than about 15 to 20 words, break it into two sentences.
  
• Scrutinize each sentence to decide if the information is useful to the reader now. If not, delete it.
  
• Ask someone else to edit your writing. You'll be amazed at how many more words a good editor can eliminate.
  

Novice Tip

As someone new to technical communication, you may find that you have some old habits that are hard to break. Here are a couple of general writing tips that will immediately improve your writing.

These tips apply to most types of technical communication, though knowing your audience is key. For an audience of software engineers or scientists, you should use terms and jargon that those readers would commonly use.

• Use short, common words. Many people think that using big words makes you sound intelligent. Normally, it does not. Using common words makes your writing easier to read and understand. Here are a few of may favorite examples:

Instead of	Use
ascertain	find out
utilize	use
indicate	tell, say, or show

• Write short sentences. They are also easier to read and understand. You should still vary sentence length so that your writing does not sound choppy, but most sentences should be short.

Novice Tip

As someone new to technical communication, you may find that you have some old habits that are hard to break. Here are a couple of general writing tips that will immediately improve your writing. These tips apply to most types of technical communication, though you may find that certain scientific journals and other types of writing require a different style.

• Use the active voice for the vast majority of your sentences. This helps readers know who or what is performing the action of the verb.

• Address your reader as "you" in most sentences. Use the imperative (command) form of the verb occasionally (as I did in this sentence) for variation.

Back to Top   Home    Our Approach    Services   Projects   Awards   Resources   Tips   Contact

Last update: October 23, 2002
© 1998-2006 TechCom Plus, LLC