Twenty One Rules for Tech Writing
One of the things that has surprised me about the readers of ME Forum is the number of folk who want to publish technical papers. When I was an undergraduate (a very, very long time ago), publishing papers was the farthest thing from my mind. I knew that publishing was a concern for some of the faculty, but it was certainly no concern of mine! To my even greater amazement, most of those desiring to write want to write in English, even though this is not their mother-tongue. I presume that this is a natural consequence of the fact that English has come to dominate the technical literature world-wide. That is a good thing for me (I only speak one language), but I would think it must be a daunting prospect for many of you. I have great respect for anyone who would undertake to write a technical paper in a foreign language; it is quite enough of a challenge in a language that I know pretty well. But perhaps it is not so much “foreign” as it is simply a “second language,” for those of you that know multiple languages. Either way, I am impressed that you would tackle this difficult undertaking at this point in your lives.
The purpose of this article is an attempt to help those of you who wish to publish, particularly technical publications. Most of what I have to say can be applied to anything you write, comments about such matters as organization, for example. Other parts of this article apply specifically to publication in technical journals, so you must use my suggestions with understand as to where they apply and where they do not.
I am organizing this article in two main parts. The first part I have labeled as Philosophy, meaning that it provides some guiding principles to be kept in mind about the way you construct your paper. The second part is labeled Mechanics and refers to details about actual construction of the paper. You will find that both of these are important. I have been reviewing papers for many years now for ASME, SAE, Journal of Mechanism and Machine Theory, and others, and I can tell you with certainty, that many papers fail on some of the most mundane items discussed here. These things matter, and if you want your paper to be accepted, you will need to pay attention to them all.
1. Have something interesting to say. There is simply no point to attempting to write a paper on an uninteresting topic, one that does not interest you, the writer, nor the reader. There are times when it is necessary to report information that is less than fascinating, but as the writer, you should seek to find what there is about this information that is interesting and/or important to the reader and point that out. You should never choose to write on a topic where you really do not know what you are talking about; it just will not work!
2. Identify your reader. In most cases, you will not know exactly who the reader is going to be, but you should have some pretty clear ideas about him nevertheless. You will be making definite assumptions about the reader (it may be helpful to go so far as to write these out), about his background and preparation for what you are going to present. Are you writing for a broad, general audience with a limited technical background, or are you writing for someone who is a specialist in the field and perhaps has even more background than you do? The assumptions you make about the reader will have a major impact on what you say and how you say it, so it is necessary to be rather definite about the capabilities of the reader.
3. Identify your publisher. When you write, you need to keep in mind who will be publishing your work. Most established publishers have very definite requirements regarding style, page layouts, footnote/endnote requirements, and a host of other matters. Many journals will publish in each issue a short section with a title like “Information for Authors,” and today this will usually lead a link for a URL where you will find pages and pages of detailed requirements. It is better by far to be aware of these requirements before you begin writing rather than having to do major re-writing simply to meet the publisher’s requirements.
4. Organize your story in a logical form. This is often not the way things came first to you, but it is necessary to make things easy for the reader. Think about the easiest possible way to explain your subject to a reader, the sequencing of information that will enable him to most easily understand the whole topic. This will help you to keep your paper concise and focused.
5. Provide any necessary background. This is often done in an Introduction where you survey related previous work so that someone not intimately acquainted with the field can still follow your work. Depending upon the nature of the publication (journal article, technical report, lab report, etc.), a bit of basic review may be appropriate in some situations.
6. Use correct terminology. Terms such as axial, radial, height, width, length, vertical, horizontal, cylindrical, conical, spherical, etc. have rather specific universal meanings. Be sure to describe carefully the orientation of dimension, and other similar matters that are often essential for a clear understanding. Consider the four words: depth, height, width, length. What directions are associated with each? Height is usually vertical, that is aligned with the local gravity vector. The length of something is usually the longest dimension, assuming that this dimension is horizontal, but what happens if it is not horizontal? The word depth is sometimes associated with a vertical distance, such as the water depth, but it is also associated with a horizontal distance measured away from the observer. The ambiguity of these words means that they must be used with great care. Often it is necessary to say something like, “The depth of the hole, measured in the horizontal plane, is ...” or “The width is 42 mm, as shown on the drawing.”
7. Use consistent terminology throughout. If you call something a brick at the beginning, then it must be called a brick throughout. If you start off talking about the engine, do not switch to talking about the motor. The exception to this occurs when you use a common place term to introduce an idea before giving the technically correct term. Consider for example, “The longest edge of a right triangle is called the hypotenuse.” The common term in this example is “longest edge,” but the technically correct term is “hypotenuse.”
8. Use figures, but use them sparingly. Figures can add a lot of interest to your publication, as well as conveying much information in a simple, easy to understand form. But remember that they are there to inform, to carry information from you to the reader, not simply to look pretty. They take up a lot of space, so they must convey a lot of information. On the other hand, they must not be too cluttered, with text too small to read. Labels with leader lines can help in many cases.
9. Always write a conclusion. The conclusion is important to solidify in the mind of the reader what it is that he has just read. When you write your final conclusion, be sure that your text supports everything that you are concluding and that you have told the whole story.
10. Don’t make you paper too long. Most journals impose a limit of 8 pages, including figures and references, so be concise. There are exceptions, journals that allow longer papers, but the best ones generally have a firm limit. If a paper becomes too long, the reader is very likely to loose interest before finishing, in which case, you have not reached the reader with your information and he has wasted his time.
11. Be precise in the use of words. Don’t describe everything as “efficient,” when you really mean “more effective,” “faster” “less expensive,” “more aesthetic,” etc. The bigger your vocabulary is, the easier this will be. Avoid “engineer–speak,” that is, the sort of slang that engineers often use on the job, such terms as “down-force,” “up-draft,” “bhp,” “mip,” “CG,” “cross-over,” etc. (Does everyone know that the CM and the CG are usually the same location, although not always? Giving the whole term makes clear which you mean.) If you think they are necessary, then you must define them in the text. In this same vein, for technical publications it is never acceptable to use the abbreviated form that have become popular with instant messaging, texting, Twitter, etc. I am speaking about such things as “u r” for “you are,” “b4” for “before,” and similar extreme contractions of words.
12. Number all figures, and provide a title. In so far as possible, all figures should be uniform in style. Think twice about the use of color. It looks pretty when well reproduced, but will it always do so? Multi-color figures on a black and white copier lose most of their information. For most purposes, black lines on a white background are the best idea.
13. Number all pages. This seems obvious, but evidently it is not so to everyone. This helps put the pages in order if they get shuffled, it helps a reviewer refer to specific items, and it helps a reader to locate information given in a citation.
14. Number all equations. Again, this seems obvious, but not so to everyone. Use conventional symbols wherever possible (Greek rho for mass density, W for weight, m for mass, v for velocity, etc.) For journal publication, do not show substitutions of numeric values into an equation. Instead, solve the equation in symbols and then show the final numeric result. There may be an exception when for a professional report (such as a stress analysis for a client), you may need to show the substitution.
15. Provide section and subsection heads. This helps to give structure to your paper, conveying the logic of your presentation. Also, it suggests to the reader where to look for particular information.
16. Start a new paragraph with each new idea. The basic purpose of a paragraph is to present one, and only one, idea. This is true even for summary paragraphs where the new idea is the interrelatedness of several ideas presented previously. Single sentence paragraphs are to be avoided.
17. Use spell-check. With all the word processing capability available today, almost all of it including a spell checking feature, there is absolutely no excuse for misspelled words. Now spell-check will not check the logic of your sentences, so the simple fact that spell-check did not flag anything does not mean that everything is correct. But if spell-check does flag a word, you must correct it.
18. Punctuate and capitalize correctly. Be sure to single space after a period at the end of every sentence. When using a hyphen to break a word, do not include a space. Punctuate consistently throughout, with the publisher’s rules as your main guide. Above all, be consistent. It looks terrible to see a space on one side of a hyphen and not on the other
19. Use consistent units throughout, usually SI. This would seem to be obvious, but it is not so to everyone. Most of your work should be formulated in such a way that it is units-free, that is, so that it may be used with any consistent system of units. But when you are reporting numerical results, you will have to use units (unless you use dimension-less ratios which are not entirely satisfactory).
20. Use abbreviations correctly. If you want to use an abbreviation, such as BWR for Boiling Water Reactor, the whole thing must be spelled out the first time, with the abbreviation immediately following in parentheses. Thus, we might say, “Westinghouse provided the Boiling Water Reactor (BWR) for the installation.” Thereafter, use BWR consistently, except at the beginning of a sentence (do not start with an abbreviation).
21. Proof-read, proof-read, proof-read! Putting the words into the computer is only the beginning of writing a paper, definitely not the end. It is necessary to proof read, looking for many different potential problems. Does every sentence make sense and say what you intended for it to say? Is your explanation complete, or are there gaps in it? Is the punctuation and capitalization all correct? Have you followed the publisher’s guidelines for format, style, equation numbering, etc.? When you have read it and re-read it many times, to the point that you think it is perfect, then get someone else to proof-read it also for you. The failure to adequately proof-read is one of the most common of failings, and it reflects very badly on the author. It says that the author did not think that this article was worth making perfect, which makes the reader wonder why he should bother with it at all?
Following these rules does not assure that your paper will be accepted by one of the leading journals of the world, but failure to follow them virtually assures that your paper will fail. The whole idea of writing a paper is to communicate something to a reader, and these rules are largely about steps that you, the author, can take to facilitate that communication. If what you say is not interesting or is unclear, then there will be no communication. These rules are all about clarity and ease of communication.