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

2. 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.

3. 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.

4. 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.

5. 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.

6. 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

7. 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

8. Examples of Writing
“After declining for days, John reconfigured the algorithm to improve performance.”

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

10. 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.”

11. 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.

12. 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

13. 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?

14. 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.

15. 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.

16. 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.

17. 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

18. Textbook Guidance Chapters 5 – 8, for general technical writing
There may still be overlap, but this will be a good guide.
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