Technical and Business Writing Tips

Automating output of Word docs to Printer and PDF

2007-10-08T23:22:00.000-07:00

Zeverix Solutions released WordOutput 1.0, software for automating the output of Microsoft Word documents to printer and PDF.

WordOutput automatically outputs multiple Microsoft Word documents to the selected printer. With virtual PDF printers, such as Adobe PDF, you can automate the creation of PDF files from Word. It also lets you e-mail or fax multiple documents using such virtual printers as PageSender. Just add the Word files to the WordOutput list, adjust the settings, and WordOutput will do the rest for you automatically.

How it Works

• Add the Word file to the WordOutput list.
Slect files from the system dialog, drag-and-drop from Finder or add all open documents.

• Select a printer and adjust the settings.
You use the same settings familiar to you from Word's Print dialog.

• Click Print.
WordOutput outputs the documents on its list one after another.

Key WordOutput features:

• automate printing of multiple Word documents
• automate creation of PDF files using virtual printers
• close each document after output or leave them open
• output all pages or a specific range
• add easily files from the system dialog, Finder, or documents open in Word

Introductory price: $24.95
Demo site is here: http://zevrix.com/demodownload.html

Choosing the right Style Guide

2007-09-24T03:17:00.000-07:00

Amanda asks, "I’m setting up a Tech Pubs Dept for a Financial Services company. What is the best style guide to encourage the staff to use?"

Frist off, the main benefit of adopting a style guide is that it puts guidelines in place to ensure consistency across all documents that go out the door.

Sounds obvious but..

Style guides don't make poor writers better writers, but they certainly are a step in the right direction!

Style guides can improve the quality and presentation of documentation. They establish a layer of professionalism that may not have been there before. They also reduce arguments and ‘loose cannons’ within the department, as the style guide becomes the acknowledged reference.

There are at least four points to consider when selecting a style guide.

1. The Reader
Consider who will read your documents and ask:

What is their reading level?
What is their expertise?
What is their motivation to read your material?
Where do they read, e.g. office, while commuting, at home?
What style do they prefer, e.g. formal or informal?

If you have different groups of readers, explore which group requires the most attention, and which guide suits their needs the most.

2. The Publication
If you’re producing one publication for the same readership, your task should be easy. However, if you're managing press releases, technical documents, web content and newsletters, one style guide may not meet all your needs... and using two could be confusing.

Most Fortune 1000 companies (with a variety of publications and audiences) use an industry standard style guide as their basic guide and write exceptions for different divisions.

For example, the Marketing Dept might use the standards in The Associated Press Stylebook and Libel Manual, but use The Chicago Manual of Style for other sections.

3. The Users
Editors value style guides. Difficulties arise when untrained staff members have to use the style guide when producing web content, reports, documents, etc.

They find manuals hard to use, (tip: AP is probably the easiest) and often simply ignore them.

To resolve this, (for the non-trained writing staff) prepare a style booklet based on your main guide. Determine the most important style points and write examples in real-work sentences.

Keep the booklet short and easy to read.

4. Your Preference
If you don't have a preference, test it. Check the most important style questions in the guides you're considering, and then edit an article using each guide.

Look at the results and once you have selected your primary guide, keep the rest for reference as each have their specialist areas.

Tips when Writing for the Web

2007-09-24T03:14:00.000-07:00

Writing for the Web requires new a different approach to the writing process. Before you start writing web content, try to understand the basics of information architecture and how navigation systems work.

On the web, write in small digestible chucks, which fit into the information hierarchy. To create your hierarchy, outline the website as you would for printed material.

Then examine the site's purpose and outline the main sections (e.g. words people use to navigate) and the links within those heads. Test it before it goes online.

You can do this by writing the heads and links on Post-IT sticky notes and put them on a chart. Show the chart to sample users. Ask them how to get from one section to another.

Next, run a usability test.

Put the outline of each webpage on a sheet of paper. Stack the pages and, sitting next to the user, hold up the pages. Tell them what to find and ask them to "click" the headings to get there.

If they choose the right pages then continue; otherwise go back and make notes.

Don't give any hints or clues on how to navigate. Sit back and watch. You’ll be amazed how their approach differs from what you had expected. Make notes for later revisions. This paper model helps you see how people navigate through the site.

By writing concise, descriptive headings, you will lead users to the content that they are seeking.

For example, do visitors expect to find phone numbers, under "Who we are" or "Contact us"?

On the web, one page on print media requires two or three screens. As readers scan text on the Web, make sure you:

Write short paragraphs
Use bulleted lists rather than narratives
Write one subhead for each idea.

Tip: Planning is 80 percent of the work.

Once you've created a good outline, the writing will have more impact.

What exactly do technical writers do?

2007-09-24T03:13:00.000-07:00

Technical writers write technical documents that explain complex issues in simple, plain English.

Technical writers - also know as Technical Authors or Information Designers - write material that supports software and hardware systems.

They design, write and produce material that is delivered in print, soft-copy or as Online Help, such as that found in the Help section of programs like Word.

How to Interview Tech Writers

2007-09-24T03:07:00.000-07:00

Jane R. in Texas asks for some tips on interviewing tech writers, especially when using assessment tests. Her company is about to hire their first full-time writer and they have not done this before.

I’ve worked on both sides on the fence in the past, (i.e. interviewed and been interviewed) and picked up a few tings in the process. Hopefully, these will be of some help.

How much time should be allotted to complete the assessment test?

I’d suggest one hour. Some people will race through it, while others will deliberate over the grammar questions forever. Nonetheless, one hour should be sufficient time for them to complete the test. By allocating this amount of time to the test, you are also emphasizing its relative importance. If it were a simple 10-minute quiz, it wouldn’t carry the same weight.

Here’s a suggested approach for administering the test:

When advertising the vacancy, mention that an evaluation test is part of the assessment process. By saying this upfront, you will ‘weed out’ under-qualified writers who know that they would not pass the test.

When scheduling interviews, remind the applicants that there will be a 1 hour test. Explain to them what this entails, for example, that there is X number of questions on grammar, procurement, technology etc. Among other things, this illustrates your company’s professionalism as you are helping the applicants to prepare for the interview.

In turn, it would be unprofessional to spring the test on applicants when they turn up and catch them by surprise. Completing the test take about 90 minutes and some of your applicants may have other arrangements to consider, such as day-care, commuting etc.

When they arrive, I’d interview them first and then do the test. If they are unsuitable for the position, you can cancel the test and say that it’s not necessary at this point. For those who are suitable, I’d do the following:

Give them a pen and paper (always helps).
Glass of water/coffee.
Find a quiet room with a PC or laptop.
Give them a printout of the test (most writers like hardcopys).
Walk through the test so that they understand what’s required. They can ask any questions at this point.
Once they are ready, leave the room and let them do the test in Word.
After 20 minutes, drop in to see how they are doing. This is not to police them, but to see if they genuinely need any assistance.
After 60 minutes return and print out their test.
At this point, I’d suggest that they have a break so that you can score the test.

Once you've completed this, sit down and go over the scores. As everyone likes to know how they performed in a test, I’d walk through the results and discuss them with the applicant.
For example, if they scored poorly in one section, ask them how this area could be improved.

And finally, I’d thank them for taking the time to do the tests and hope that they’ve gained from it.

How many points for a passing score?

You could use 40 for a pass and disqualify anyone who comes in below this. Most experienced writers should get between 60-80 depending on their skills.

What I’d look for here is an imbalance in the scores. For example, if someone failed most of the grammar questions, but did very quite well in other sections, discuss this with the writer.

You may discover that many writers have no formal writing training and will suffer in the sticky grammar questions but compensate in other areas.

I’d use the scores/results to assist the overall interview process, i.e. you have material in front of you that you can discuss with the applicant and explore their abilities as a proposal writer.

You could also ask for their thoughts on this evaluation process and if they had suggestions to improve it. This might give you some insight into writers with potential management or creative thinking skills.

Problems with Table of Contents in Word

2007-09-24T03:02:00.000-07:00

James in North Carolina asks, "In Word, the Table of Contents is not displayed. Instead, I get an error message: { TOC\O "2-4"\H \Z \T "HEADING 1,1"}. How do I fix this? Is it a bug? "

I think the problem is to do with Field Codes.

Here are three suggestions:

1. In Word, go to Tools > Options > View tab and click off Field Codes (if this is selected)

2. Close Word.
Open Windows Explorer and search for Normal.dot.
Delete all copies of Normal.dot!
Re-open Word.
It will automatically re-create a new Normal.dot, which may be the correct default settings

3. In Word, on the Tools menu, click Options.
Click the Print tab, and then clear the Field codes check box.

Let me know if you know other ways to fix this problem in Word.

Ivan

Controlling large docs in Microsoft Word

2007-09-24T02:58:00.000-07:00

The main issues with creating long docs in Word tend to involve formatting, styles, graphics, tables, and bullets.

Formatting — cutting/pasting material directly from one file into another is best avoided as this will bring unwanted styles in the target Word file. Instead convert it to raw text and then import it.

Styles — create specific styles and avoid over-riding settings. Avoid using the default settings in the Normal.com template file.

Graphics – avoid using cut/paste graphics into Word. Instead, reference them with Insert Picture etc.

Tip: insert graphics only after all other content has been built! Tables — avoid the default Word auto-format settings. Bullets — use styles to create bullets. Avoid using the toolbar and menu options to create bullets. Avoid over-rides.

WARNING: Bullet lists cause more damage than any other feature in Word!

Always turn off Allow Fast Save and Save Auto Recover. See Tools > Options > Save > Allow Fast Save.

Developing Microsoft Word files with these pointers in mind will help reduce the file size and avoid corrupting the document template.

Podcasts about technical writing

2007-07-30T12:16:00.000-07:00

Check out the excellent Harry Miller's Technical Writing Blog

Podcasts about documentation, technical writing, and technical editing.

http://blogs.msdn.com/harrymiller/default.aspx

Robohelp Patch released - Internal error encountered, Failed to generate WebHelp

2007-07-30T12:14:00.000-07:00

When trying to generate a merged project from Adobe RoboHelp 6, you get these error messages:

"Internal error encountered, Failed to generate WebHelp."

and

"Warning: [path to file] cannot be copied to [path to output]. reason: source does not exist."

Follow this link to the Adobe site for the patch: http://kb.adobe.com/selfservice/viewContent.do?externalId=kb401652&sliceId=2

Free PowerPoint Templates Packs

2006-11-29T11:17:00.000-08:00

Microsoft offer several free PowerPoint Templates Packs on its Download Centre site.

http://www.microsoft.com/downloads/details.aspx?FamilyID=3a8b90ac-2bcb-4fec-a8b4-bfbd509baefb&DisplayLang=en

This download is a collection of background and design templates included with PowerPoint 4.0 and later versions.

Free 2007 Microsoft Office Add-in: Save as PDF or XPS

2006-11-29T11:08:00.000-08:00

If you've just bought or are planning to buy the new VISTA product, make sure you get these freebies from Microsoft.

This free download lets you export and save to PDF and XPS in eight 2007 Microsoft Office programs.

It also allows you to send as e-mail attachment in the PDF and XPS formats in a subset of these programs.

Full details here: http://www.microsoft.com/downloads/details.aspx?FamilyID=4d951911-3e7e-4ae6-b059-a2e79ed87041&DisplayLang=en

Can't drag a slide from PowerPoint 2007 to Word 2007?

2006-11-29T09:56:00.000-08:00

You may get an error message when you drag a slide from PowerPoint 2007 to Word 2007

As well as the slide not appearring in the Word 2007 document, you receive the following error message: Word has encountered a problem.

To get around this problem, follow these steps:

1. Open the PowerPoint 2007 presentation that contains the slide you want to use in Word 2007.

2. In the Slide pane, locate the slide that you want to use.

3. Right-click the slide, and then click Publish Slides.

4. Click Browse, locate a folder to which you want to publish the slide, and then click Select.

5. Click Publish.

6. Exit PowerPoint.

Next, open the folder where you saved the one-slide presentation in step 5.

7. Open the Word 2007 document into which you want to insert the slide.

8. Locate the page on which you want the slide to appear.

9. Drag the one-slide presentation from the folder that contains the one-slide presentation to the page.

Added technocrati Code

2006-11-26T09:45:00.000-08:00

Added code to setup account.

Technorati Profile

Who can be a Technical Writer?

2006-11-25T11:57:00.000-08:00

Punita Jasrotia offers advice for anyone considering tech writing as a career.

Salary expectations range from:

"A technical writer today can start with an average salary of about Rs 10,000-14,000 and earn up to Rs 35,000 in 2-3 years. An individual can start at the entry level as a technical communicator, to become a senior technical communicator (2-3 years experience), a writers’ team leader (with 5 years of experience) and move on to become the director of technical communications (10 plus years of experience). "

Key skills include:

* Better scope for a science graduate with a one-year computer diploma course.
* A postgraduate degree/diploma in English literature, journalism, science or Electronics/Computers with a background in creative writing.
* Knowledge of DTP tools, development tools (RoboHelp) and web tools (HTML and XML coding is a definite advantage for an online environment.
* Basic knowledge of computer hardware, operating systems, software applications and programming languages is an added advantage. Familiarity with Windows and applications running in the Windows environment is a MUST.

http://www.expressitpeople.com/20020805/cover.shtml

Tech Docs Resources

2006-11-25T11:30:00.000-08:00

Great starting place for locating information about User Documentation:

Technical Documentation

User Manuals

Computer Based Manuals

Online Help

http://www.usernomics.com/documentation.html

Get feedback to improve your technical writing

2006-11-25T11:26:00.000-08:00

John West asks how do you know whether you are writing well?

"There’s only one test that really matters: when your audience understands your information and is moved to act in accordance with your goals. But how will you know when this happens? The odds are pretty good that, early in your career anyway, you won’t have any automatic indicators. Sometimes you will be writing a decision paper, and your decision will be adopted as the company line, and this is a good self-test. But this won’t happen often; more often than not early in your career your writing will not be directly acted upon.

Usually you’re going to have to solicit feedback."

http://onlytraitofaleader.com/2006/10/03/how-to-improve-your-technical-writing-get-feedback/

Podcast re: Technical Writing in India — Sandeep Balakrishna

2006-11-25T11:15:00.000-08:00

For Indian readers considering tech writing as a career, download this free podcast with Sandeep Balakrishna, a seasoned technical writer based in Bangalore, India.

"He has been a technical writer for 10 years, and has observed the explosive growth of technical writing in India. According to Google Trends, seven of the top ten cities where the term “technical writing” is searched is India. What does that mean? Is outsourcing growing or shrinking? What is the Indian perspective on technical writing?"

http://techwritervoices.com/2006/10/30/technical-writing-in-india-an-interview-with-sandeep-beepu-from-bangalore-india/

Common errors in technical writing

2006-11-25T11:08:00.000-08:00

Intrepid offier notes from a session of the Mumbai chapter of the Society for Technical Communication.

The first session was by Gurudutt Kamath, who is probably the most well-known figure in the tech writing community in India.

"My interest in attending the session arose cause someone I know was also speaking there, and also because a lot of the work that we do involves a significant amount of technical writing. So while, we may not be professional technical writers, consulting does require us to have excellent written communication skills."

http://everydayentrepreneurs.blogspot.com/2006/10/common-errors-in-technical-writing.html

Technical writing: the new black gold of India

2006-11-25T11:00:00.000-08:00

The Economic Times reports that India's attention is focussed on its earnings from software, but the actual black gold may now come from technical writing and not just codes. The newspaper estimates that there may be 5000 technical writers in India today.

Rahul Prabhakar, who runs a network called the Technical Writers of India (TWI) says: "There are 2,000 of us on the TWI network alone."

The leading indian publication quotes a "recent survey by TWIN found that about two-thirds of Indian technical writers were engaged in some form of writing before switching to technical writing. Most of these technical writers were in journalism, copywriting or research-oriented writing.

http://economictimes.indiatimes.com/articleshow/2221687.cms

Adobe kuler Released - Free Download

2006-11-25T09:22:00.000-08:00

This month's release from Adobe Labs is kuler, the first creative, hosted web application designed both to stand alone and to complement Adobe Creative Suite 2 components.

Created with Macromedia Flash and ActionScript 3.0, kuler is all about color: color for exploration, inspiration, experimentation and sharing.
What is Kuler?

kuler is a hosted web application from Adobe Labs designed both to stand alone and to complement Adobe® Creative Suite® 2 components.

What can you do with kuler?
Search, create, share and exchange color themes online. Download kuler color themes as an Adobe Swatch Exchange (.ASE) file for use in Creative Suite 2 components, as well as in individual versions of Adobe Illustrator® CS2, InDesign® CS2, Photoshop® CS2, and GoLive® CS2.

Cost?
kuler is being released free of charge as a technology preview to give you the chance to check it out and take it for a test spin.

http://labs.adobe.com/technologies/kuler/

Electronic Forms in Office 2007

2006-11-24T10:17:00.000-08:00

Those of you involved in developing electronic forms, should take a look at this article from James Morgan.

"The 2007 release streamlines data collection through integration between InfoPath 2007 and the core applications. Electronic forms can be presented as standalone forms in the InfoPath 2007 client or in the browser, imported into Groove 2007 workspaces, embedded in Document Information Panels and Task Panes, or embedded in Outlook 2007 e-mail messages so colleagues can complete forms without leaving the familiar Outlook environment."

Key features are listed at:

http://jamorgan.wordpress.com/2006/11/20/support-for-electronic-forms-in-office-2007/

Andre Da Costa on Office 2007

2006-11-24T10:00:00.000-08:00

Andre Da Costa provides a very detailed review of the new Office 2007 package.

Based on his experience, it was awarded the following scores:

Installation: 95%
Ease Of Use: 85%
Features: 93%
Improvements: 95%
Design: 94%
Options: 95%
Help/Documentation: 90%
Price: 85%
Overall: 91.5%

He highlights that the "ribbon in the core applications is a bold step forward, but its necessary, 1,500 commands and a plethora of toolbars have pushed the antiquated interface to the limit and it’s just a matter of time until the Office team makes the Ribbon standard across the entire modules in the Office System."

When discussing whether the benefits outweigh the changes, he adds that "getting used to the interface should not be a problem for many since the familiar tools are organized in ways that makes it convenient for the user to access both new and previously hidden features.

This makes the interface more intelligent and more aware of what the user is doing, presenting the right tools for the Task at hand. I am proud to say; this is an Office release I definitely look forward to using everyday."

http://www.activewin.com/reviews/software/apps/ms/office2007/conclusion.shtml

Office 2007 may be Microsoft's Titanic

2006-11-24T09:47:00.000-08:00

The Australian publication IT Wire has an interesting angle on the new Office release.

Dr Steve Hodgkinson, the recently departed Deputy CIO for the Victorian State Government, believes that Office 2007 could well be a disaster that Microsoft has created for itself.

"The new version Microsoft Office... is headed for a giant obstacle with major sites in both the public and private sector. Cost of product upgrade aside, Dr Hodgkinson believes the migration will be a hard sell.

"The migration effort, including training, has created an obstacle for them," says Dr Hodgkinson. "Microsoft will have to work really hard to make the migration path as trouble free as possible."

http://www.itwire.com.au/content/view/7234/53/

Screencast Tutorials

2006-11-24T09:39:00.001-08:00

Techsmith (the people who make SnagIt) have launched a website focussed on their new screencasting tool.

It's worth a look if you're interested in web content development and/or technical documentation.

Signup for a free trial account here:

http://www.screencast.com/signup.php

Go to the turorial section: http://www.screencast.com/help/userguide/addnewset/index.php

FAQs about the Office Activation Wizard and reduced-functionality mode in 2007 Office

2006-11-21T11:47:00.000-08:00

For those who want to know more about the Microsoft Office Activation Wizard, please take a look at this FAQ on the MS support site.

"The 2007 Microsoft Office suites include an Activation Wizard. To fully use a retail version of a 2007 Office suite or program, you must activate it. If you do not activate the product after you install it, the 2007 Office programs can be started only in reduced-functionality mode. In reduced-functionality mode, 2007 Office programs function more like viewers.

In other words, you cannot save modifications to documents or create new documents. Additional functionality may be reduced. No existing 2007 Office files are damaged when a product runs in reduced-functionality mode."

http://support.microsoft.com/kb/927921