Feature
Writing Effective Editorial Comments
By Dhupinder K Malhotra
Editing is one of the most powerful and widely used means for ensuring the quality of a document. Editors first ascertain the intended audience and their expectations from the documentation, based on the user's information needs. Next, the editor reads and comprehends the document to validate its content. In the process, they also spot and try to correct any technical, semantic, structural, or grammatical flaws.
While an editor can immediately make edits for flaws that they are sure are flaws, in situations the editors might think that they cannot make edits without the consent of the authors. Or, an editor might think that the author should provide some additional information or rework on certain areas of the document. Editors use comments to pinpoint such areas in a document that require the author’s attention.
In this article, I discuss the “what”, “when”, and “how” of comments in the context of electronic editing.
What are comments?
Comments highlight areas in a document that require the author’s attention or action. Visualize them as flags in a document seeking the author’s attention or directing a user to take a corrective action. Generally, editors insert comments for the author of the document. However, authors can also insert comments for an editor, or one editor might insert a comment for another editor. The rationale behind editorial comments remains the same in every scenario - they require either an action or a note to be taken for something in the document. In this article, I focus on the comments that an editor provides electronically for the author’s attention.
Editors can specify comments for the author in two ways:
- Placing the comments within the document using the built-in commenting feature of the text editor within the authoring application.
- Specify the comments outside of the document by referencing the sections within the document that require the author’s attention. This information can be enclosed in an e-mail accompanying the reviewed document.
When to insert comments?
An editor can insert comments in a document under any or a combination of the following situations:
- When the document has ambiguities and contradictions. For example, consider the following text from a document:
As you may have noticed, the binary IP address in the first sentence differs from the binary address in the calculations. What is the correct binary address for Machine A?
- When there is a lack of clarity in the text of the document because of improper sentence construction. This can happen when the document has been written in a hurry and the author could hardly get time to self-review the document. For example, consider the following text:
- When the author “seems” to have deviated from the original context. One of the reasons for this apparent deviation could be that the necessary connections between two or more disparate sections are missing. This might happen if the author assumes that the readers will be able to provide the necessary context themselves. In such a situation, the editor and author jointly need to analyze the expertise level of the targeted group of readers and take an appropriate action.
- When the document is incomplete. The document can be incomplete at either a micro or macro level. At a macro level, the document may not have covered the required information. For example, a document discussing the causes of a problem X, may list a, b, and c as the causes, but may discuss only causes a and b. An editor’s comment, in such a situation, can inquire the reason for non-inclusion of cause c.
A micro-level issue may manifest itself as information missing from a specific unit, section, or paragraph of the document. An editor may come across a document containing test items for an online course, in which feedback for a particular test item includes feedback for the correct answer only, and none for the incorrect options or the distractors. The editor’s comments, in such situations, may ask the author to fill in the missing parts.
- When the given information may be complete, as a self-contained unit, but inadequate for the purpose of the document. Extending the example from the previous point, an author may provide feedback for the correct answer as well as the distractors; however the feedback may not truly justify why the correct answer is correct and why any of the distractors isn’t the correct answer.
Or, perhaps, the document may use an abbreviation or an acronym without first acquainting the user with its expansion.
- When the author uses (a) term(s) inconsistently within the document. For instance, use of “datastore” and “data store” to refer to the same entity - a storehouse for data. This is a very simple term. An editor may encounter inconsistent use of technical terms that they may not be familiar with. They may not be in a position to correct the inconsistency without prior consent from the author. An editor’s comment may inquire about the correct usage in such a case.
- When the editors want the authors to ensure that the edits made in the document do not, inadvertently, alter the intended sense. For instance, an editor may delete some repeated information from the document, or reorder certain paragraphs. Perhaps, the redundant information and the original order of paragraphs are an intentional act.
- There can be other situations, such as non-working hyperlinks, insufficient information about the source of an image, non-compliance with the templates or formats prescribed for a document, and incorrect calculations. Consider the following text:
Here, the sum of respective percentage market shares of Companies X, Y, and Z adds up to more than 100%.
How to write Comments?
A good editorial comment, just like a good error message for a software product, should convey the following information:
- What is the problem?
- What is the possible cause of the problem?
- What is the suggested remedy to correct the problem?
Following are some guidelines for writing effective editorial comments:
Insert complete and precise comments, providing all the three components of a good comment, as discussed above. Whenever authors encounter incomplete or vague comments, they may send the document back to the editor for clarifications, the editor may clarify, and the author may then respond back with the corrected document. These round trips can be a real threat to the timelines.
An editor’s comments should always describe the problem in detail and help the author address the problem by suggesting solutions. For instance, if there is a fault in the author’s sentence construction; rather than asking the author to rephrase the sentence, an editor may provide alternative construction(s) to the author. The author can then validate the accuracy of the sentence or enhance it further.
Insert global comments (at the top of the document) to bring the author’s attention to issues present at multiple locations in the document. For instance, an editor may write a global comment requesting the author to use the authoring templates, indent and format the code properly, or, perhaps, ask the author to refrain from using colors in the document. If it is feasible, insert a comment wherever the situation referred to in the global comment occurs in the document.
However, if the effort involved in editing the document before and after the author addresses the global comments is equal, it is a good idea to ask the author to address the global comments prior to editing.
Note your observations in a comment along with (a) supporting argument(s) and some source (reference to a book or a web site) validating your standpoint. If you differ from the author at a particular point in the document, these comments will support your opinion.
Comments should never be personal or harsh. An editor needs to be very careful with the choice of words for their comments. The objective is to provide constructive feedback that will enable the author to improve the document, not to attack or belittle the author.
Ensure that comments are complete and grammatically correct. Avoid using slang, jargon or short-hand. Doing so will improve your credibility with the author.
Volunteer to assist the authors with managing the editorial comments in the document. Some authors may need assistance with the technicalities of viewing, inserting, editing, and deleting editorial comments in a text editor, or with understanding the electronic editing process.
Never put comments like “Same as the previous comment”, “Same as the next comment”, or “Same as second comment”. If the authors delete the referred comment, chances are they may end up referring to the wrong comment.
While the commenting process is one of the methods of interaction between an author and an editor, a direct, in-person interaction between the two individuals has advantages. Reviewing the comments with the author reduces transmission time by providing an opportunity for the author and the editor to together to create a high-quality document. However, such in-person communication may not be feasible in all setups. Regardless of the type of interaction between an author and an editor, editorial comments should have the power to bridge all gaps and help produce a high-quality document.
************
Dhupinder K Malhotra works as an Information Developer with India Software Lab (ISL) of IBM. A graduate in Mathematics and a post graduate in Computer Applications, Dhupinder has been involved in editing, technical writing, e learning, and web content development for the past 4.5 years.
IBM is a trademark of International Business Machines Corporation in the United States, other countries, or both. Other company, product or service names may be trademarks or service marks of others.