Bridging the Gap

As a technical writer, when you have approached for the services of a dedicated editorial department and have received the edited version of your document, you might be perturbed by the intensity of editing that has been done. This experience is normal or it might be possible if you have not worked with fervent editors or not yet acquainted with their editing approach. Nevertheless, whether you are a fresher or an experienced technical writer, the advises given here will aid you to take decisions to finalize your contents or write-ups for the final publication. These guidelines also help you to have good rapport and a long lasting prolific relationship with the associated editor:

• Train your mind to stay calm and poised when you see those extensive editorial markings. Never be defensive. For instance, if a comment or a markup disturbs you, refrain to retort straightaway. On the other hand, consider the matter with regard to the message it carries, and not the criticism. Later, accept the comments or the edits with stride or reject it with confidence based on information you have at hand.
• An editor reviews your work objectively. While reviewing the documents, editors engage themselves with a focused mind and help the writers to craft an improvised version. Have faith that there is no amount of any sort of bias. Therefore, writers should make the most of this fact by carefully considering any structural modifications, comments, or suggestions. Editors would let you know the flaws in your document in terms of organization or if there are any grave inconsistencies in technical information.  So, appreciate the impartiality and trust editors’ perspective because they read with audience in mind and respond to the information or the content.
• When you work with a substantive editor, there is every possibility that the editor would recommend that you do a significant rewriting and paraphrasing. Based on the experience of the editor, writers are suggested to add quality content depending on the references and style guides they use. Therefore, writers should be mentally prepared and willing to rewrite the document.
• Editors propose standard writing conventions and replacement (substitute) words. Sometimes, these are discretionary changes made because the editor considers that a better word usage or a rephrased sentence reads in a better way. In this case, writers can feel free to disregard the changes unless there are any suggestions to change unclear statements or grammatically incorrect sentences.  Having said that, if you as a writer, strongly believe in restricting a change, approach the editor about the logic for revising the content. If the editor justifies that the modification rectifies an error, record or save the comment for future so that you can avoid repeating such mistakes in your forthcoming updates or versions.  If a particular edit is optional, but strongly directed, use your judgment and take a call about accepting or rejecting it. Editors would summarize their edits to improve unclear or long-winded content, or generate a review tracker to comprehend what the writers are trying to communicate. By doing so, sometimes they may be unsure of the writers’ intent or may ask them to confirm that  after revision. Again, writers should use their discretion and must not fret. 

To sum up, writers should accept their shortcomings with grace. Editors would be more than happy to know that they encouraged writers to come up with something better.  Professional editors are unbiased and diplomatic, but at the same time should avoid making comments in an incorrect way. Sometimes, even editors misinterpret the content or inadvertently falter. If writers catch an editor’s erroneous edits, they should go ahead and inform the editor. Editors in turn should appreciate the approach and accept their shortcomings too. This piece of advice is for editors as well to take the feedback from writers constructively.

Like It or Hate It, but Do Not Ignore It…

It is said, “It can be a peer, rather than a customer, find a defect.”

 

This one-liner statement intensively endorses that peer reviewing is an obligatory process in the life cycle of documentation. Therefore, it is recommended to have regular and an effective peer review process in place that is recognized as a powerful system to improve upon certain technical aspects or sentence-level issues in the documentation.

 

To achieve a good end result, make the peer reviewing process a priority and a habit. It is decisive to understand that this process is an important step to be completed before a document is published or project is complete. Peer reviews must contain constructive criticism and the goal is to improve the team’s documentation or project-specific metrics and not to deride someone’s writing or performance.

 

Preferably, a qualified professional or a member of the team who is principally accountable for the project must perform the peer review. The work on the document must be peer reviewed from a professional standpoint and view point of the reader/user.

 

Follow the points given here in the peer review process:

 

• Be candid and unbiased, yet polite while offering criticism. Offer criticism with aplomb in your comments; after all quality matters here. Do not make personal attacks anywhere in the comments. This can only cause differences among the participants in the review process and it does not indicate authors/writers clearly as to how to improvise their writing.
• As you point out the weaknesses or errors in a piece of writing, it is appreciative if you can also indicate the positives. Bring up facts to the writers’ notice as to why something is particularly correct or why not.
• Substantiate your suggestions with a rationale and propose the writer the right direction as to how they might improve the work for future releases.
• Ask questions so that the writers have to clarify their points or find ways to improve or rectify the information or sentence structure.  
• Always understand that time is a constraint (time taken for your review and for the writers’ revision). So, focus on the most important area where the document could be improved.
• Finally, provide a memo (or a reviewer’s report) that summarizes the findings and include a note on scope for improvement.

The responsibility of the peer reviewer does not end here unless the reviewer receives a response from the writer. Therefore, it is beneficial if writers too summarize their responses to reviewers so that it facilitates a 360-degree feedback that brings the review process to a closure. To realize this:

• Writers, after receiving the feedback in the form of comments and/or recommendations, should respond to the reviewer by acknowledging the changes made or actions taken against each comment.
• If there are reasons for not following certain recommendation or changes, let the peer reviewers know the reason so that that they can avoid commenting on certain style or known issues in future.

 To summarize, it is important to perceive the peer reviewing process more in terms of collaboration or teamwork and perhaps mentoring thereby making helpful suggestions for improving the documentation.

Consistency: Editors’ winning tip

Editing is all about four C’s.

CLEAN – Text is free of errors.
CONCISE – No redundancy in the text.
CORRECT – Technical information and assertions are verified.
CONSISTENCY – Text is uniformily edited.

From an editor’s standpoint, the first three C’s can be managed by using spell-check tools, grammar rules, interaction with writers/SMEs/engineers. However, the skill to edit a document with a methodical CONSISTENCY is easier said than done.

One of the important tasks in editorial involves meticulous capture of inconsistencies. That is where we say “Eye to detail” is crucial. For a certain term or a word usage, where more than one correct option exists, an eye to detail becomes very much indispensable. For example, 100 percent, 100%, and hundred percent all mean the same thing. No matter which way you write it, the readers will understand. But the credibility is recognized when the editor monitors or catches inconsistencies with an eagle’s eye. In such situations, editors must ensure that dealing with language around “percentages” is consistent throughout, but also that it matches the customer-specific writing standards.

How consistency can be achieved?

Remain focused in your task. Staying focused is a challenge. To achieve the objective, clear all unnecessary distractions. Especially while you are editing a large document, set a target to complete small chunks of text within stipulated time. Regulate the breakdown of task for an hour’s effort. Then, concentrate on the document with the customer requirement in mind.

While editing, try to remember your edits that are done earlier in the document. If you feel that you cannot commit to your memory, jot down certain keywords, hyphenated words, capitalized/ unique terms, terminologies in a notepad and maintain them as your word checklist. By using this checklist, standardize the document for consistent word usage by using the Find and Replace option in the editing tool. Judiciously follow writing standards and adhere to customer-specific writing standards to avoid ambiguity.

Consistent edits appear in the documents with practice and experience. Consistency is also achievable through collaborative work environment and enormous amount of persistence. Editors should set a challenge on themselves to get zero defects or negligible review comments from peers. Editors must meet up for a periodical review and exchange their learning/findings regularly. They must regularly interact with other editors, directly or indirectly, as their respective efforts to improvise on consistency.

All the Proof You Need….

Proofreading is the final stage in the editorial process – the final quality control (QC) check-through before publishing the text. However, proofreading must be practiced in our day-to-day written communications as well.

 

A vigilant proofing or proofreading is important to ensure that the write-ups or contents in a document are accurate and consistent. In other words, every book that goes finally to publishing or every e-mail that is being composed to client or the stakeholders of the organization has to be essentially proofread at least once. This re-look is obligatory to pay utmost attention to quality. Proofreading assures that you have not missed any awkward inaccuracies in your writing.

 

Why to proofread?

 

As stated earlier, proofreading is absolutely necessary to maintain quality. To reiterate its importance, here are some technical and principled reasons why one should vouch for proofreading.

 

The fact is, no matter how many times you have read and re-read your writing, there are chances of typos and mistakes because you are too close to the matter or subject when you are writing. This is a bit weird but true. To put it in simpler terms, when you are very familiar with the subject, you get blind spots. So, your eyes fail to read exactly what is on the page and you tend to miss errors. Sometimes, you do not realize that a mistake is made. Typos, grammar slips, and inconsistencies are extremely disconcerting, and they might even challenge the image of writer/editor.

 

Therefore, proofreading is a significant part of documentation process and it is recommended to set aside a considerable amount of time for proofing each time you pen down.

 

How to proofread?

 

There are different methods to perform the proofreading task. Choose the one that best suits you. Here are a few of them that can be considered as guidance:

 

• Read the text slowly.
• Read the text aloud and also silently.
• Read text backwards to focus on the spelling of words.
• Have others read it for a second check.
• Point the text with your finger or mouse pointer to read one word at a time.
• Print it out and read it. (This method applies to e-mails or write-ups with a modest word count.)
• Be careful that your eyes do not jump from one error to the next apparent error, thereby missing some subtle errors in between.
• Double check for small and little words such as or, of, if, it, and is and most importantly the homophones, for example, here/hear are often interchanged.

Note: Proofreading does not involve improving the writing style in any way. So, while proofreading refrain from editing or modifying the writing style.

Copy edit lingo

Copy editing is one of the levels of editing in DDLC. Copy edit focuses on detailed review for grammar, spelling, word usage, and punctuation errors. Copy edit also offers suggestions for better presentation of content and ensures that the document adheres to the pertinent standards.
During the review process, editors make the edits or place sticky notes on the document to communicate their edits to the writer. Certain terms / editing lingo or abbreviations are used in the editorial comments, which the writer needs to understand while incorporating the edits.
The following table will help writers to understand some of the terms used in editorial post-its or comments.

All caps: Text in CAPITAL LETTERS. Caps—the short form for capitals.
Art: Illustrations in the document.
Back matter: Content at the end of the document or book: appendixes, glossary, bibliography, index.
Body text: Bulk of text in between front and the back matter.
Boilerplate text: Template text or text that is not subjected to any changes.
Callout: Notes or text in the illustration.
Flush left: Text alignment to the left.
Flush right: Text alignment to the right.
Front matter: Content at the front of the document or book: title page, copyright page, table of contents, list of illustrations, list of tables, preface.
Full measure: The width of the text page.
Global note: Change or edit that applies to the entire document.
Init cap: Capitalizing first letter of each word (other than prepositions, articles, and conjunctions) in titles, headings, or text. Also, known as title case.
Lead cap: Capitalizing first letter of the first word of a sentence. Also, known as sentence case.
Lead lines or leader dots: Dotted lines in between the entry and the page number in table of contents.
Lead-in sentence or stem sentence: An introductory text that precedes the listed items and concludes with a colon.
Legend: The text that accompanies an illustration. Also called caption.
Lowercase: Small letters.
Mini-TOC: Page that introduces the specific chapter. Usually contains the section headings as entries.
NP: Next paragraph/New paragraph.
Orphan line: The first line of a paragraph that appears alone at the bottom of a page.
Style note: Refers to specific style mentioned in the style guide.
Serial comma: Comma preceding and or or in a series of items (a, b, and c).
TOC: Contents page.
Typo: Misspellings.
Uppercase: Capital letters.
Widow line: The last line of a paragraph that appears alone at the top of a page.
X-ref: Cross-reference.

Checklists in documentation

Having a comprehensive checklist is like covering an entire, voluminous style guide in a nutshell. Ideally, a checklist would consist of series of items wherein each item has a checkbox that needs to be selected if the item is taken care during writing or review process.

Preparing checklists is a tedious part in documentation. Nevertheless, it works to our advantage. As we assemble points to prepare a checklist for a given review, the entire scope of the review becomes very understandable.

It is very difficult to track or keep in mind all the points while reviewing a document without use of checklist. Checklists come in handy when just about to begin the job. These would significantly lessen the chances of missing out on various necessary standards to be followed in designing and writing technical documents. Furthermore, using a checklist is a way to more easily check and validate whether a document complies with the template or a specific style guide.

The effect of using the checklist is profound. Instead of just beginning to write or review a document, we look intently at every little detail and make sure that we are in the right track.

Checklist makes our reviews organized. It keeps our mind focused. Checklist saves our time by ensuring consistency and completeness while performing a review.

Writers and reviewers should remember to revise their checklists when new updates are made. When we have a checklist for a complete process, and when we strictly adhere to the checklist, it is rest assured that everything is in place.

Employ self review in documentation

It is appeasing to the eye and mind to read information that is crisp, easy to grasp, and error free. Therefore, it becomes important to produce premium documents not only for the look and feel, but also to promote superior image of the organization. When we produce excellent quality documents, it does mean that we are sensitive to customer centricity.

We understand that every document needs to be reviewed and edited. In some cases, there is a designated editor in place to edit documents, but in majority of the cases, most writers must rely on peer writers or review it themselves. This implies that writers have to review and revise the content methodically before they submit their documents for editorial review.

Writers should set aside of their time for self review. The self review process is similar the editing process, but it serves a very different purpose. While editing ensures a clean and grammatically correct document with consistent style, self review finds or points out inaccuracies.

Writers should read through their drafts and ensure that the content adheres to their respective style guide standards. While reviewing the drafts, writers should continue to improve accuracy and clarity of the content. For example, they have to look in for any sentences that can be made more effective by rephrasing.

Most importantly, writers should prepare an internal checklist for self review. This should be done mainly based on the comments from editors. By doing this, the checklist is enriched and updated, and writers can never miss out on some of the important issues while reviewing.

Self reviewing a technical document ensures minimal comments from the editorial team, and hence, in due course, writers can produce documents that are seamless.