You have a new job and an exciting career ahead. You have dreams of being one of the most accomplished Technical Writers around. You wait for your first task and here your manager gives you a huge word document to edit. What do you do? Edit, of course you say, but a teeny voice in you is nagging you with: “How do I begin?” “What if I miss something?” “Why am I given a document to edit when all I want to do is write?” type of questions.Do you hit the panic button or do you just jump in to do the task? My suggestion: “Have a Plan”. You can refer my earlier blog on the “The Beginners guide to Reviewing and Editing” to know more about planning your task and making a good job of it.
For now let us focus on the key points to consider when you edit. Being a good editor is like passing the litmus test to become a good writer. You need to be a good critic to write good articles and editing teaches you to be that critic. It is less likely that you will be trained to edit, you will definitely be expected to show your ‘On the job’ competency and ‘Learning curve’.
The following general guidelines can be followed to edit any Word document:
- Enable ‘Track Changes’: Never forget to do that. You would not want your feedback to be misunderstood or worse ignored because it was not tracked properly. Any changes you do must be recorded and must be available as feedback for the author.
- Ensure the Word document settings are set to reflect your name as the Reviewer. It is especially useful when you are adding comments for the author(more about adding comments in further steps). Click on File tab -> Options. Ensure your name is reflected under the ‘User Name’ Text box. Input relevant initials.
- Add comments: in relevant places to elaborate on the mistakes you have found. Sometimes authors might find it difficult to understand their own mistakes. They might need more clarity and explanation. Adding comments is a good way to ensure that. Click on ‘New Comment’ in the Review section of Word to add comments.
- Review in Passes: Always do the Review in more than one pass. Do not attempt to finish your editing in a single pass. Its hardly ever efficient. The more numbers of times you read through the document the more mistakes you will find. Do a formatting check in the first pass. Technical Review in the second pass and so on.
Note: There are many kinds of editing; this post focuses on editing a word document containing Technical information related to the Software field. Treat it as a general thumb rule that can be modified to suit your editing needs.
Note: Remember to stick to your timelines , more than 5 passes is not only impractical but also unnecessary.
Checklist for Editing
- Adherence to Standards and Guidelines(S&Gs): Every company follows a style guide for their documentation needs. It could be a custom made company style guide or general style guides like ‘Microsoft manual of style’ or ‘The Chicago Manual of Style’. Ask your manager which style guide needs to be referred to before you begin your edit.
You must ensure that the document content and layout adheres to the particular S&G. For example, you will have to check the Header and Footer content and layout, the font size, face and color of the contents in the document and so on. Most of the formatting checks will be done under this category. - Adherence to 4 C’s: Every Technical Writer knows that the Writing must follow the 4 C’s rule- Clear, Concise, Complete and Correct; and every Technical editor knows that he has to ensure each statement follows the 4 C’s.
- Clarity: You need to do a Readability Check. A
document’s efficiency is measured by its Readability and
Clarity. An editor’s job is to ensure that the document
serves its purpose to the concerned audience. Is the message
behind the given information clear? Do you have to re-read
it to understand the underlying message? For example
consider the following two statements:
“Data is calculated or the field uses the stored data
based on a formula”.
“Field displays either the stored data or the data
calculated using a formula “.
Which among these two statements convey the message intended
by the author clearly? The intended message is: “The field
displays either the data retrieved from the database or the
data calculated real time using a formula”. Let me know which
you think is a better statement. If you can improve on it
please feel free to do so.
Readability check includes the following parameters:- One message per sentence: Each sentence
must convey a single message. - Content appropriate for the intended audience:
A User Guide and a Maintenance Manual are
intended for different audiences. The content must vary
according to the audience. - Check for Colloquial words and Jargons:
Technical writing world frowns upon Jargons and Colloquial
words. Weed it out.
- One message per sentence: Each sentence
- Conciseness: Use simple statements. Technical writing
is better appreciated when it is written in simple language. Do
not use flowery language. For example: “He woke up at 3 am in the
morning”, this could be re-written as “He woke up at 3 am”. It is
understood that ‘am’ refers to morning. - Completeness: The statements have to be complete. For
example: “Input the text there”. Where should the user input the
text? Such incomplete statements must be weeded out. It could be
rephrased as: “Input text in the textbox” - Correctness: You must ensure all the statements are
correct. You need to do the Language and Grammar checks to ensure
the correctness of the document.
Consider the following parameters when you check for correctness:- Article usage: Ensure correct usage of
Articles - Tense Usage: Past, present or future tense,
ensure consistency - Voice usage: Active voice or Passive voice.
Active voice is usually preferred in Technical Writing,
especially when you give instructions - Usage of Person: Second Person is preferred in
Technical Writing. - Use of Singular/Plural Words: Even though
equipment is plural “The equipment are heavy” is a wrong
statement. “The equipment is heavy” is the correct statement.
Careful editing is required in such cases. MS word usually flags
such grammatical errors but it’s the editor’s job to double
check. - Punctuation check: Check for appropriate use of
semi colons, commas, colons, parenthesis, hyphen, exclamation and
period. Exclamation is avoided in Technical Writing.
- Article usage: Ensure correct usage of
- Clarity: You need to do a Readability Check. A
Note: The layout of the document varies according to the type of the document. For example a User guide will have a different layout from a Product Brochure. Refer to relevant sections in the S&Gs to get a clear idea on the Scope of your work.
These are the few things you check in a document during the Editing process. Refer your company S&G to get detailed guidelines on editing. Remember S&Gs keep changing and it’s a good idea to stay updated.
Have I missed an important editing rule? Let me know which ones and I will thank you for the tip.:)
Good one!!!