Self Editing Tips

This article will help you when editing your own work. Most of these tips are equally relevant when peer editing.

  • Before you start editing ask yourself when, where, why, and how the document will be used.
  • Even if you prefer editing online, take a printout of the document when you are doing the final edit. You may miss certain things as you edit online.
  • Editing requires extreme focus and concentration. So perform edits when you are not pressed of time or have no deadlines to attend to. The best time to edit any document is when you start your working day in the morning. You are back to work after a break and it helps you see the matter with a fresh mind and perspective.
  • Edit in small doses. The longer you edit without a break, the less effective you will become. Divide big projects into sections you can edit completely without tiring your mind.
  • Don’t try to find everything at once. Skim for some things (such as fonts, spacing, missing illustrations). Then, go back to check out some other thing. That is, do a few rounds of edits, each focusing on a particular type.
  • If the document is too complex, read the draft several time. First read the content to check the user level and general organization of the information at. Later look again for other problems such as clarity of language and other intricate details.
  • Add to your checklist any common errors you know you make and anything you feel needs to be checked or verified for that particular document.
  • Use a style sheet and a checklist as you edit. Keep them handy and refer to them when required.
  • Don’t overlook the obvious. Pay attention to the document title, document number, version number, and chapter or section titles, page numbering, and so on.
  • If you have used materials from another document or chapter, check that any required changes (such as the product name) have been made.
  • Check the line breaks and page breaks. Transitions to the next line or to the next page are common problem areas.
  • Look for symbols that come in pairs—parentheses, brackets, and quotation marks.
  • Double or triple-check equations. Check calculations.
  • Avoid language-edits at the same time as you perform substantive editing. It slows you down and will also distract you.

Spare some time to write a summary of your thoughts, observations, impressions, criticisms, or feelings about the draft. Categorize your comments according to the type of problem or error.

Skills of an Editor

Editing generally means different things to different people. It is also true to say that no two editors edit a document in the same way. It is difficult to define the exact duties of an editor and it is even more difficult to define the skills of an editor. Editing is a craft and an art, and practice makes it perfect. So it is helpful to follow certain rules and guidelines and polish the skills required to make a good editor.

If you look at the advertisements, you will see a variety of titles: technical editor, copy editor, editorial assistant, editorial specialist, documentation editor, etc. This makes it very difficult to understand what the organization is actually looking for and the skills they are looking for in an editor. It is equally difficult to say if they have invented such titles just to lure the candidates to do some boring and mechanical job.

Actually each of these titles have a specific definition. The candidates in these posts have specific tasks to perform. But we shall not go into these details here. Considering all these factors, we can generalize that the technical editors should have the following skills:

  • Ability to make style related decisions rather than choices.
  • Ability to enforce these decisions.
  • Be a team person with good communication skills.
  • Be well-versed in grammar and punctuation.
  • An instinct for recognizing patterns, creating categories, and organizing ideas.
  • Have an eye for detail, layout, organization, and page design.
  • Think logically to re-write any technical material following the defined document templates, styles, and standards.
  • Willingness to question assumptions, theories, and facts.
  • Ability to recognize what is missing in content, argument, or presentation.
  • Ability to improve the skills of the writers to a certain extent.
  • Ability to edit fairly without any personal feeling (friendship or rivalry) affecting the work.
  • Have adequate time management and project management skills. Editors usually work on multiple projects. Very often they write their own document and peer edit others work too. So there should be fine balance of time and priority.
  • A basic understanding of the subject that is being edited. Without such a background, editors will be limited in their ability to address the technical accuracy of the document.

Some technical communicators suggest that technical expertise might limit the effectiveness, of an editor making it harder/difficult for them to remember how little a layman might know about the subject. However serious problems can arise when editors do not understand the subject at all.

Importance of Technical Editing

Regardless of how remarkable your document is or how well organized the material is, if it contains grammatical and spelling errors, the reader will probably not trust the document. A misspelled word or incorrect use of a word can take away the credibility of the entire document you have written. Little errors and inconsistencies in the usage of words can confuse your readers. Editing is the process of checking information to correct content, language, and stylistic errors.

Technical editing is revising a document that presents material related to science or technology to make it communicate more effectively. The main purpose of editing is to make sure that the audience gets an error free document. It is the process of reviewing a document to improve its language in terms of content, accuracy, coherence, and consistency.

Editing is very subjective term. If you ask five people to describe what it means to them, you will get answers as varied as the parabled five men who described different parts of an elephant. The truth is, good editing goes unnoticed, but even a single spelling mistake in a document brings in a lot of negative comments. Take a look at the following cartoon and poem. There are no spelling mistakes (typos), but are they error free? On the contrary, it is full of errors/mistakes.

 1

 The poem and the cartoon speaks volumes about the importance of the human eye taking a look at the document to find the mistakes. Though the spell checkers can be useful for finding some errors, they will not find correctly spelled wrong words (e.g. wait instead of weight) or double words such as “the the”. Some desktop publishing tools perform grammatical checks and may locate errors like double words.

Good editors know that they do a thankless job and this makes them even better. Remember, being a good editor is like being a masked superhero (or super girls) working behind the scene.

  • Writers don’t take editors seriously—Some writers have a very great self opinion and resent being edited as they feel that their writing is being questioned. As a result, editors must occasionally deal with stubborn writers who make not even incorporate the edits. The life of editors become rather difficult in such scenario because as professionals they trust the writers to do their part of work—incorporate the changes in the documents.
  • Good editing is invisible—The problem with writing is that no one appreciates good writing when they see it. The users are probably not aware that they are using a good document. But they quickly come to know that a document is not good. Good editing goes invisible, but bad editing stands out like a sore thumb. So, if you are not criticized for your editing, it means that you have done an excellent job.
  • No appreciation—Unfortunately most of the time, there is no appreciation for the work done by the technical writers as compared to the development teams.
    • When a document is error free and well organized, the writers may walk away with the recognition and the praises. Many a times, the editor had to make a few passes of edits to make the document remotely accurate, user friendly, and usable.
    •  After the product releases, the development team may sometimes include the writers for the release celebrations, but the editor is conveniently forgotten!

Advantages of Planning a Project

Planning the documentation project helps you in the following ways:

Reaching an Agreement

  • You can consider all the aspects of the documentation efforts when you plan it. You can think over the project and make all the decisions up front, rather than as you write. So you have all the agreement on the approach to document setup before you start writing.
  • If the project involves more than one writer, you can get an agreement from them regarding their responsibilities on what you intend to do, so that all are clear about their part in the project. Difference in views can be taken care of in the initial stages of the documentation effort.

Formalizing Certain Aspects

Planning helps in formalizing the following components:
• Project goals and objectives.
• Scope and expectations of the document.
• Roles and responsibilities of the team members.
• Assumptions and constraints.
• Quality management approach.
• Project management approach.
• Ground rules for the project (anything that is different than usual).

These can be grouped into separate topics in the documentation project plan.

Uncovering Problems

For large documentation project, as you start planning it in detail, you will uncover the problems before you start writing the document.

  • The plan will help answer questions regarding what goes into the manual, where it is to be added, the style to be used, etc.
  • You can avoid doing/redoing some tasks if you anticipate certain problems at the starting of the project.
  • It saves hours of rework or delay which germinates from unclear goals and missing information.
  • You have time to look for and decide alternate course of actions.
  • You can plan some buffer time for solving problems, right at the planning stage.

Documentation Process: Importance

When something goes wrong in a project, it is easy to blame an individual as the cause of the problem or for deviating from the desired quality, process, or schedule. This is where procedures help. Procedures are nothing but standard approach of doing things.

A good process is akin to a highway. Though it is made to ensure smooth and fast travel, there is a likelihood of head-on collisions with vehicles coming from the opposite direction, at certain junctions. Keeping an eye open for such junctions and having considerable room to manuver within the cross roads avoids collisions. Similarly, you have to explore and define each of the areas prone to accidents and collisions during the planning process.

Manuals have a bad reputation, often for good reason. The good documents don’t get the credit they deserve because the bad one gets all the attention. The worst part is that writers get the blame, even when they are given inadequate time, tools, and support to do the job. — Michael Bremer

Problems like unclear procedures, inadequate information, language errors, and, online help that is difficult to navigate, lead to inefficiency and reduced productivity of the users. So it is important to have an effective process that will help reduce errors and improve usability of the documents. It is not enough to say that the document must be error free. It is equally important to define the acceptable quality, and the methods to meet it. Hence, the documentation effort should also be well planned, not just thrown together at the last minute to meet a deadline.

An effective documentation process helps reducing the problems as it:

  • Defines the practical steps you must perform to achieve quality results.
  • Contains a list of tasks to be performed.
  • Provide a framework on how to perform the tasks and activities.
  • Defines the accepted degree of accuracy and errors and thus increases the likelihood of success of a project.
  • Explains the set of activities to be carried to efficiently complete a quality documentation project.
  • Specifies the tasks, objectives, roles, responsibilities, process description, references, quality records, and authorization details.
  • Provides confidence that the work done in a certain way is acceptable.
  • Provides consistency of results—if everyone follows the same process and procedure, they will be doing things the same way, reducing the probability of making errors.
  • Provides a ready-made reference to a newcomer and thus reduces the learning curve.

Limitations of Procedure/Process

Processes do not make mistakes. People do. Processes are the tools that help you avoid make the mistakes. Inspite of all the advantages, these are some limitation of the procedures and processes:

  • A process may work well for some projects/products, but not for the others. In such a situation, it is better to adapt to an alternative workable variation in the process than to blindly follow the prescribed procedure. Sometimes you may have to perform some additional tasks not listed in the process, and sometimes you may need not follow all of them.
  • Although the process describes how certain activities should occur and be performed, sometimes experience helps you make the right decision. Experience also helps you understand the issues to make good judgment on how to proceed, specially in unknown situations that are not addressed by the procedures

Importance of Project Plan

Planning is the most important aspect of a documentation project. A good plan provides a basis for every action that needs to be performed. It helps you frame the projects so that you can work towards a goal. It is very unfortunate that in most organizations, documentation planning is usually regarded as something to be done after the development phase is complete.

Careful analysis and planning are integral parts of the working life of a technical writer. You cannot have quality in a project which is not properly defined and/or planned. You need a predefined structure to produce quality documents in a predictable and reliable manner. Though the basic approach may remain the same, the planning process may vary for organization to organization. To produce an useful documentation, consider it to be an integral part of the product development phase.

The trouble with plans is that they are based on the way things are now. To be successful, your plan must focus on what you want, not what you have. —Nido Qubein

Very often, projects change so much that you diverge from the original plan as youprogress. So, planning at an initial stage may sometimes seem to be a waste of time,but no one can deny that it works as a road map that points to a destination. You canalways change it as you develop the document.

  • As soon as you get a project in hand, the temptation is to start writing. Starting immediately is the worst thing to do because you are more likely to hit the writers block and wonder what to write and how to write. In the process, you will end up with a poorly written document.
  • Sometimes, the project may get into such slippery grounds that you are not sure about what is happening and what is to be done. In such confusion, you can refer to the plan and get right back on the track.
  • The plan enables various people in a project to agree upon the contents, design, and other such details of the project before starting the documentation efforts. The product and documentation managers agree and approve of the way you intend to handle the documentation.
  • The plan is a formal agreement between the project manager, documentation manager, writers, and reviewers regarding the dates, formats, and other issues. Create the plan and get it reviewed and approved by the people involved in the project. This way, the management is aware of the effort that will go into creating the document and you will also have their agreement on certain aspects of the project.

Importance of Domain Knowledge

An ongoing debatable question is, do technical writers need domain knowledge? OR What is more important—writing skills or subject/domain knowledge?

What is more important—your right hand or your left hand? If I am not mistaken, both are equally important. You may be little more comfortable using one over the other. The same stand is applicable to writing skills and subject/domain knowledge. The writing skills get you the job, where as you learn the subject on the job. Good audience analysis includes knowing about your users and their requirements. So, apart from the primary competencies (language skills, knowledge of tools, grammar, writing skills, critical thinking, etc.) domain knowledge is also important for succeeding as a technical writer.

So it is important for you to learn about the domain you work in, be it engineering, finance, medicine, law, gardening, database maintenance, or rocket science. You can’t do a good job if:

  • You have excellent language and writing skills, but don’t know the subject you have to write about.
  • You are a technical expert, but lack in language and writing skills.

A few years back, technical writers were seen as language experts. Now, many organizations advertise for writers with technical background. This is because people have now realized that technical writers are not just linguistic experts. They perform a lot more activities and tasks—writers also have to understand the concepts, theories, ideas, designs, and code to effectively communicate them.

Having subject matter knowledge can mean:

  • Having sufficient knowledge of the subject to effectively communicate about it.

What is more important than knowledge of a technical subject is the ability to understand the subject and write about it. To write different types of documents you require a different level of understanding of the domain/subject. You should have the ability to understand the subject (software, engineering, accounts, inventory, law, medicine, science, health, business, etc.) and express it in writing. You can be an effective communicator only if you understand and know about what you want to communicate.

Example:If you have to write about electronic products, it would be extremely helpful if you have an electronics background. It is not necessary, but is surely helpful to you as it saves time and effort required for training, understanding the concepts, and reviewing the documents.

You don’t need to master the technology, but you should be a fast learner.

  • Having the critical analysis skills to comprehend and understand complex, technical, and scientific concepts. For instance, a technical writer should:
    • Know about the subject not the code to write GUI related information of the product and/or software.
    • Have a basic knowledge about the code to write for advanced users.
    • Know something about the equipment to write the installation procedures.
    • Know everything about aviation and the working of the aircraft to write an operations guide for an airplane.

Writing different types of documents for different industries requires a different level of understanding of the domain/subject.

  • Understanding the technology just enough to confidently explain the technology.

Even if you don’t have the relevant background, it is very important to be able to understand the basic concepts of the technology, irrespective of the subject. It will help you describe complex technology clearly and concisely. As a writer you do not need the knowledge required to design and build the product. If you have some knowledge about the topic you have to write about, you can learn the new product faster and write about it better.

Example: You must have come across sales people in automobile and electronic showrooms. They know just enough about the products they deal with, to give the precise information to impress the prospective customer. They talk about a model (television, microwave, automobile, etc.) and then move on to demonstrate the features of the next model. They can give a good comparison about the features and the cost of various models of the product they are trying to sell.

Technical writers should neither know more nor less. This is almost like adding the right amount to spice and salt to a dish.

As a technical writer you write about technologies which already exist and products that are already created! So, you need not possess an in-depth knowledge about the subjects, but you should definitely have to be a fast learner and also need to have some amount of interest in the subject you write about. In short, the interest in learning new technologies, ability to grasp and understand the concepts quickly, and the ability of explain technical concepts to the users is what you need!

These days, many organizations want writers with strong technical skills. You may have come across advertisements for writers with specific background—finance, instrumentation, pharmacy, aeronautics, electronics, etc. to write about their product. There is also requirement for writers who can read and interpret Java, Visual Basic, or C++ code.

Knowing the tools and having excellent writing skills will help you in this regard. In some technical writing positions, having technical qualification and competence is an important success factor as it will help you in the following ways:

  • Planning better: It will help you plan your project in a better and effective manner.
    • You can easily identify areas that need to be documented in different types of documents (user’s guide, functional specification, systems requirements document, installation guide, etc.).
    • You can understand the importance and the implications of the functionalities. This makes it easier to create the content accordingly.
    • You can prioritize tasks based on these inputs.
  • Conversing intelligently: Having good knowledge about the subject helps you to intelligently converse with engineers on complex software (database, communication, network engineering concepts, to name a few).
  • Organizing: It will help you organize large quantities of technical material in a better and efficient manner.
  • Saving time: Knowing the technical concepts saves time as:
    • You do not have to spend a lot of time researching, reading, and understanding the product/technology.
    • The SME’s do not have to explain to you the basic concepts of the technology.
  • Reasoning skills: It is but true that physics, chemistry, mathematics, and computer graduates (apart from engineering) have better reasoning skills than the social sciences and arts graduates. It has nothing to do with intelligence. It is all about training the mind to think in a specific manner.

Let me wind up saying that the emphasis of technical writing is in the field of software which happens to be the largest segment of the technical writing market (atleast in India). Your knowledge can be in other areas, such as engineering, medicine, manufacturing, finance, and law. This is not an important criteria, but it definitely gives you an edge over the others and the opportunity to get into the related field.