BLOG

Finalizing your technical document: A clean, well-lighted place

With a long technical document such as a research paper or technical report, I've found it's impossible to read through the document once and evaluate all structural, content, and formatting isseditpass graphicues at the same time. Using a checklist can be useful. It helps you look at each aspect — the structure, the content, and the formatting — in a systematic way. In the checklist below, some items assume the standard journal article structure (abstract, introduction, methods, results, conclusions, references) for a research study, but they can be adapted to other structures, such as a review article or white paper.

The whole idea is to remove any barriers to understanding between your readers and your document: Think of a solidly built structure, a house with good bones, clean, well-organized, nothing out of place. No visual obstructions. Clear windows, lots of sunlight. Your text, tables, and figures are lucid and easy to follow, with no verbal obstructions or areas of confusion. Nothing distracts your readers or keeps them from understanding your content. That gets you published and gets your findings out to your audience.

Hints:

  • Make a quick separate pass through the document for each checklist item.
  • Try to view the document with fresh eyes (or enlist someone to do this for you).

 

Technical Editing Checklist

Organization/structure review
• Does the document have the appropriate sections for its purpose?
• Are the subsections nested properly?
• Is material duplicated in more than one section? (not a good idea, except in the abstract)
• Is ordering consistent through the document? (eg, same ordering of endpoints in methods and results sections)

Substantive review
• Is the purpose/objective of the study/report clearly stated?
• Do the conclusions address whether you met the objective?
• Does the abstract include a brief description of the study objective, study design, results, and conclusions?
• Does the introduction give a clear picture of how your study is related to past studies and why it is being conducted?
• Are references included for all statements related to published findings?
• Does the methods section describe sample size, enrollment criteria (if applicable), material preparations (if applicable), a detailed description of the study design, measurement parameters and endpoints, and statistical analyses?
• Are the results presented logically (eg, from the most important to least important, or chronologically)?
• Do the results include specific wording to indicate the statistical test performed?
• Are tables warranted to present the data? Using a table will often improve text readability and will always highlight the findings.
• Are figures warranted to illustrate the data? Using a figure will make the findings more easy to grasp at a glance and will always highlight the findings.
• Are the conclusions clearly supported by the results?
• If any data are cited to support the conclusion, have they been presented in the results section? Do not introduce any new findings in the conclusions section.
• Have you explained any shortcomings of the study?
• Consistency cross-checks:

  • Abstract vs. each subsequent section
  • Methods vs. results (results for each stated endpoint/analysis, presented in same order)
  • Results vs. conclusions (conclusions follow from results, presented in same order)


Editorial review
• Read through the document, preferably aloud, and correct the following:

  • Word usage that could be interpreted in more than one way (this warrants a blogpost of its own!) or that is grammatically incorrect
  • Run-on sentences (if you have to track backward to unravel the meaning, it's too long)
  • Run-on paragraphs (can material be chunked into shorter paragraphs of 3-5 sentences?)
  • Material that's in the wrong section (eg, repeating methods info in results section)
  • Too much/too little detail in the abstract
  • Inconsistent terminology

• Do section headings reflect section content? Are they consistent?
• Is section numbering (if applicable) done correctly?
• Do all subjects/verbs agree (singular vs. plural form)?
• Is verb tense consistent and correct through the document?
• Are all style conventions followed (eg, numbers, spacing, punctuation, abbreviations, capitalization)?
• Is spelling correct?
• Is grammar correct?
• Are acronyms defined only on first usage in the abstract and again on first mention in the body of the document?
• Is the table of contents (if applicable) up to date and correctly formatted?
• Are all internal cross-references correct and working? These could include links to a table, figure, appendix, or another numbered section of the document.
• Are figures and tables numbered in the order of citation? If in-line with text, are they close to their referencing text?
• Do figure and table titles reflect content? Are they consistent?
• Are all in-text reference citations in consistent format and present in the reference list (if applicable)?
• Do reference citation links work (if applicable)?
• Does the reference list contain all of the referenced publications in the correct order?
• Are page headers and footers set up correctly?

Formatting review
• Is all text in the appropriate style (eg, font type and size), and is the text formatting consistent throughout the document?
• Is pagination done correctly with no undesired large empty spaces and no blank pages? Pay particular attention to tables, figures, or lists breaking across pages.

For a fascinating exploration of the benefits of checklists in many domains, check out Atul Gawande's "The Checklist Manifesto".

Blogger: Ginny Fleming, Founder, Lucidize Medical & Scientific Editing. Chief capacities: medical, scientific, and technical writing and editing.