DSW Home at The University of West Georgia

Log On

Computer Science

Rationale

In Computer Science, simply being able to implement a technical solution to a problem (i.e., write a program) is not enough.  Especially in this day of team-based development, it is necessary that you (as a CS professional) communicate your thoughts, ideas, technical solutions, etc. to your peers in writing.  Examples of such communication include:

·         source code comments

·         user manuals

·         help screens

·         software requirements documents

·         bug reports logged in an issue-tracking system

·         design reports documenting a proposed software architecture

·         program FAQs

·         program tutorials / HOW-TOs

·         patent applications

·         web sites

Why do we bother with documenting our programs, design processes, etc.?  For one, the programs we write are not intuitive to use, no matter how much we may believe they are.  What may be obvious to a CS professional is not obvious to others; explanation is required.

Similarly, in the CS profession it is common that you will be working with source code that other people have written.  Likewise, other people will be working with source code that you write.  Source code by itself is a complete and accurate description of the program but it is complex and cryptic, making it hard to understand – even for the person who wrote it!  Plain-language descriptions of its classes, methods, and overall design help you and others understand the code quickly and accurately.

Table I lists the DSW-related learning outcomes found in CS major courses.  These illustrate the importance attributed to writing within the department.

 

Course

Learning Outcome

Description

CS 1301: Computer Science I

CO-07

Document moderately complex classes using a documentation tool.

CS 1302: Computer Science II

CO-01

Create and specify the software design for a medium-size software product using a software requirement specification, a specified program design methodology (e.g., object-oriented), and appropriate design notation.

CS 3211: Software Engineering I

CO-03

Create a software requirements document.

CO-06

Specify a software design using an appropriate design notation.

CO-12

Write clear and accurate technical documents.

CS 3212: Software Engineering II

CO-02

Develop and implement an incremental, iterative development plan.

CO-05

Plan and conduct design and code reviews.

CO-08

Develop a plan for re-engineering a medium-sized product in response to a change request.

CO-13

Write clear and accurate technical documents.

CS 4982: Computing Capstone

CO-06

Write clear and accurate technical documents.



Expectations

The exact requirements of a writing assignment in CS will vary based on the goals of the assignment.  As an example, however, consider these characteristics of a well-written technical report:

1.       Organization: a well-organized technical report subdivides the relevant information into smaller, easier-to-digest sections.  The arrangement of sections is such that the report “tells a story”, incrementally giving the reader the information they need. 

2.       Format: a well-written report is neat and tidy.  For example, margins should be consistent throughout the report and fonts should be appropriate (e.g., Times New Roman or Arial for “normal” text and Courier for source code).  Formatting tools such as titles, section headings, and lists should be used to label and separate distinct sections of text.  Samples of acceptable formatting can be found at http://www.acm.org/publications/submissions.

3.       Context: a well-written technical report gives the reader the context they need to understand it.  For example, a software design in the Unified Modeling Language (UML) is meaningless without some textual description of the problem it solves.

4.       Visualization: a well-written technical report is not just text.  It also incorporates visual elements such as graphs and tables to display data, UML diagrams to describe a software design, or network graphs to illustrate a network architecture.

5.       Proper grammar, punctuation, and spelling: are not optional.  At the least, pay attention to your word processor’s spelling and grammar suggestions.  A better solution is to make use of the English Department’s Writing Center for suggestions on how to improve your report.

6.       Originality: your report should be your original work.  Copying another person’s work and passing it off as your own is called plagiarism.  Any time you incorporate material from another source, whether as a quotation or summarized, you must cite your source.  This act of attribution shields you from charges of academic misconduct.  Examples of proper citation style can be found at http://www.acm.org/publications/submissions.