Choosing the right Style Guide
Monday, September 24, 2007
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.
Labels: technical writing
Full link 3:17 AM,
, links to this post
Tips when Writing for the Web
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.
Once you've created a good outline, the writing will have more impact.
Full link 3:14 AM,
, links to this post
What exactly do technical writers do?
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.
Labels: technical writing
Full link 3:13 AM,
, links to this post
How to Interview Tech Writers
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.
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.
Labels: tech writing
Full link 3:07 AM,
, links to this post
Problems with Table of Contents in Word
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
Labels: tips, troubleshooting, word
Full link 3:02 AM,
, links to this post
Controlling large docs in Microsoft Word
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.
Labels: word tips
Full link 2:58 AM,
, links to this post
Technical Writing Ireland
What We Do
We’re a team of writers with an average of 10 years tech writing experience. Our focus is on delivering high-quality documentation that meets your objectives, schedule, and budget.
MS Word Template Design
PS: If you cant find the template or business document you're looking for, send me a "Request A Template" email. Let me know what you're looking for and if we don't have it in our library, we can design it for you asap.
About This Blog
This blog discusses technical writing, proposal writing, making money online, as well as MS Word tips and tricks.
Credits
This is an open source template designed by Andreas Viklund
