How to edit a technical document
The technical
editor s aim is to make a document consistent both in language and format. For example,
if a function is called "autocorrect" in Chapter 1, it should be called this in
all sections.
Don t change
it to "auto-enable" later on for no reason. Aim to be consistent. Inconsistent
writing is not interesting for the reader it s just confusing.
Be consistent
Style and
presentation formats need to be consistent. All main headings should appear the same;
subheadings should also appear the same, but appear less important than the main headings
i.e. smaller font size.
If your company
has a style guide, follow the sections on words and formats. The style guide may
need to be adapted for online publications if it does not address online document
production. Otherwise, use a recognized guide such as the Chicago Manual of
Style.
Use familiar terminology
Readers like to
understand text quickly and don't want to spend time unraveling the meaning of words or
insider terminology. On the Internet, use terms that are globally accepted to mean the
same thing.
For example,
most users understand the term Homepage . Using the term Main Channel instead
will only confuse readers.
Try to use what
is generally accepted.
Another example
is with online forms.
When shopping,
users fill in the name, address, part number, etc., and clicks a button to progress. Most
websites call this button, "Add to shopping cart" or "Add to Order."
It is familiar to most online customers.
However, if the
website renames the button "Submit", it will confuse the customer. Submit
implies that the transaction in now complete and the order will be completed, i.e. your
credit card will be charged. Users will not be sure what happens when they click the
button.
Most abandon
their shopping carts at this point.
Simplify graphics
Web graphics
need to be very clearly presented. Monitors impose visual constraints, such as low
resolutions and small screensizes.
On small
screens, one-pixel thin lines and small text is almost unreadable. Use intuitive
color-coding to clarify the graphics meaning.
A workflow
diagram, for example, could have one process in blue and another in red. Important
graphics should require little scrolling. Good editing creates a consistent look
throughout the publication.
Organize text
The basic
guidelines for online text involve:
· Break up
large text blocks. Lengthy text needs to be split into more digestible chunks or
at least separated by headings, white space and graphics.
· Keep
text in context. Check that content, such as context sensitive help, make sense
in relation to its location. The content may be accurate, but the location may be wrong.
· Be
consistent. Users get confused when terms change meaning. For example, the
presentation of Online Help should be similar in appearance so that users recognize it as
online help and not anything else. Other functions, such as pop-up dialog boxes, should
have a different appearance.
· Consider
recognized standards. When users access an online help file, they expect it to do
certain things. Any variations on the standard---such as embedded help or tutorial
help---should be introduced and explained to the user.
· Consider
Global audiences. Web writing should be reduced to the essentials and word choice
kept to the Standard English guidelines. Editing should capture and remove words and
structures that confuse non-native-English readers.
Your Thoughts?
What are your thoughts on this? Drop me a line at ivan
at klariti dot com |
I'm Ivan Walsh, the person behind this site. I help people improve how they write, publish and extend their business assets.