csci3081/class-repo-public/Assignments/CSwriting.md

CSCI3081 Fall 2017

Writing Assignment : Responding to Writing in CS

Due: Monday, September 25 at 10:00pm

Introduction

There are many different types of writing in computer science. This assignment gives you a chance to reflect on an example of your choice and, ignoring the technical content for the moment, reflect upon just the writing style and approach to determine what makes it successful or unsuccessful.

Your Assignment

Find one piece of computer science writing that is of interest to you and read it.  This can be online or hardcopy material, and "computer science writing" can be interpreted widely here.  In this class, we are interested in software design and development, so you might look for some writing that relates to software design patterns, coding style, libraries or toolkits for software development, or even research on software engineering.  Anything a software developer might find useful as a part of doing his or her job, honing his or her skills, etc. is fine -- pick something that is interesting to you.  The writing should be more than a couple pages long. Once you have read the material, answer the following questions in a typed document with separate headings for Question 1, Question 2, etc. Submit a PDF of your responses directly to the Writing Assignment link in Moodle.

Question 1 

What is the title of the writing and where can it be found? Give a citation or URL. 

Question 2

What is the purpose of the writing?  For example, is the purpose to present a new technique, describe a software testing plan, argue for adopting a particular methodology for software design, etc.?

Question 3 

As best as you can tell, who is the intended audience? 

Question 4 

At the end of this page is a list of Elements of Successful Writing in CS that was recently compiled by the faculty in the Department of Computer Science & Engineering.  How important is each item on this list for the type of writing that you picked? Copy the list below, and for each item, rate how important you think it is using the following scale:  (a) extremely important, (b) useful but not critical, (c) not very important, or (d) not applicable.  Note, we are not (yet) asking you to judge the quality of what you read based on these "successful elements".  First, let's just establish which of these elements are most important for the type of writing (e.g., a scholarly report, a blog post, a user manual, a programmer's style guide) you have selected.

Question 5

Now, let's evaluate the writing.  What do you think is the most successful element of the writing (e.g., a good organization and logical flow, good use of visuals)?  Write one paragraph to explain why you think this element is so critical to making the writing work for the intended audience and purpose.

Question 6 

Finally, what is the least successful element of the writing?  Write one paragraph to explain how the structure, visuals, organization, or whatever other element you think is weak in this example, limits the writing in achieving its purpose for the intended audience.

Elements of Successful Writing in CS:

1. States key information clearly (important findings, recommendations, ideas, issues, etc.). 
2. Addresses the target audience with an appropriate tone and level of explanation. 
3. Presents any needed background explanation clearly or informatively. 
4. Persuasively justifies a choice of algorithm, design, problem approach, problem solution, etc. 
5. Describes algorithms, data structures, software system components, etc. accurately. 
6. Describes algorithms, data structures, software system components, etc. informatively and concisely. 
7. Uses terminology and notation correctly. 
8. Explains high-level ideas with low-level details. 
9. Presents low-level details clearly and accurately. 
10. Uses appropriate structures (e.g., lists, diagrams, equations, code samples, etc.). 
11. Includes clear and informative tables, diagrams, references, etc. 
12. Smoothly integrates tables, diagrams, references, etc. into the text. 
13. Has a good organization and logical flow. 
14. Uses correct grammar, spelling, and mechanics. 
15. Avoids including irrelevant information, overemphasizing less important material, or writing verbosely.