Effective Tips for Writing Concisely and Clearly in Computer Science and Computer Engineering

Writing for CS and CE CSCE 481 Dr. Scott Schaefer Acknowledgment Prof. John Keyser & Aakash Tyagi

Shorter is Better Don t use many words when fewer will do Worse: The function utilizes a looping structure to iterate over the list while analyzing whether or not one element is larger than the next. Better: The function checks if the list is sorted. CSCE 481

Avoid Indefinite Pronouns Don t use unqualified pronouns particularly it and this Worse: The source code produced an error due to the input. Therefore, it was re- written. Better: The source code produced an error due to the input. Therefore, the test case was re-written. CSCE 481

Active Voice Avoid passive voice Worse: The source code was a mess. So the code was rewritten. Better: The source code was a mess. So John rewrote the code. CSCE 481

Organization Paragraphs should have a theme or idea associated with them. Paragraphs are not jumbles of sentences. Avoid stream of consciousness writing. You know what you were thinking while you were writing no one else does. CSCE 481

Audience Make sure you are writing to the appropriate audience Usually, this is to others in the field Not to novices they will know the basics of the field Not necessarily to just the foremost experts in the area they will not be familiar with every bit of prior work Not to experts in all areas they may not be familiar with simpler concepts from other fields Some papers (e.g. literature reviews, user manuals) are for more general, less expert, audiences CSCE 481 25

Audience Give them the background they need to understand your work Particularly if you rely on another technique; don t make them read other papers before they can read yours Not always possible sometimes there is too much to do Notation might not be standardized Explain the notation as needed The concepts might already be known CSCE 481 26

Examples of Writing After declining for days, John reconfigured the algorithm to improve performance. CSCE 481

Examples of Writing After declining for days, John reconfigured the algorithm to improve performance. His algorithm had to process alot of data. CSCE 481

Examples of Writing It becomes the ethical responsibility of companies and programmers to implement that highest standards they can and discover designs that convey information in a way that ensures public safety. Applications for this can include short range wireless systems for vehicle safety, using machines to gauge the parameters of oil wells, and cloud-based resource systems for government agencies that improve protection. CSCE 481

Overstating/Understating Do not oversell your work Do not promise more than you deliver Do not try to make your work have more impact than it reasonably does You probably have a higher opinion of your work than others do or ever will. Readers are annoyed if they spend their time reading your paper, only to find it didn t do what was promised. CSCE 481 30

Overstating/Understating Do not undersell your work Don t put in so many disclaimers that you discourage someone from reading/following it Point out problems, especially key ones, but: Your goal is not to point out every conceivable flaw If necessary, point out why problems might not be so bad CSCE 481 31

Overcoming Objections Think: If I were a reader, what would I have questions about? Find a way to address those directly If they are technical concerns and you have not addressed them in the work, show that you ve thought about them What examples should be included? What tests should be provided? CSCE 481 33

Figures and Captions People will usually look at figures before they read the text You want the figures to stand on their own as much as possible Be sure that your captions clearly describe what is in the figure. Do not rely on the text to describe the figure. CSCE 481 34

Comparisons to Prior Work Always a tricky proposition Your goal may be to show how good your work is. You have spent a great deal of time on your own approach. You must be fair to prior work, but you probably can t devote as much effort to replicating it. If standardized comparisons can be made, use them If you implement another method for comparison, be sure to do your best with it If not, be sure to clearly state what you did not do, and why. CSCE 481 35

Comparisons to Prior Work It is not OK to just present your material and assume it should be accepted That does not show any new contribution over the state of the art Exception: if it is truly the first time someone has accomplished something If you cannot provide comparisons, at least provide concise, clear arguments that evaluate your method vs. other methods. CSCE 481 36

Feedback If possible, get someone else to read your work They should be willing to give direct, honest feedback Take their evaluations to heart When readers reply with objections, don t blame the reader If the reader didn t understand it, it s probably your fault Make sure that you address their concerns Sometimes it is only a style/writing issue! Sometimes they have found more fundamental flaws Even these can sometimes be addressed by writing differently. There are (very rare) exceptions where readers are way off Always be polite and respectful in your responses, anyway CSCE 481 37

Textbook Guidance Chapters 5 8, for general technical writing Chapter Executive Summary Algorithm Description Proposal Chapter 2 Getting Started (Research Planning) Chapter 3 Reading and Reviewing (Literature Review) Chapter 4 Hypothesis, Questions, & Evidence Chapter 10 Algorithms Chapter 11 Graphs, Figures, & Tables There may still be overlap, but this will be a good guide. CSCE 481