Why Writing Matters

Why Writing Matters in Computer Science

"Building software is one of the most complex endeavors the human mind is capable of.  Much of the process is abstract and managed by paper.  It is critical that students learn how to effectively communicate in all forms."

~Scott James, Computer Science and Information Systems Department

Why Writing Matters in Computer Science 

Much writing about software is poorly written.  Often when programmers are asked to write, they hate it.  Many companies hire tech writers to fill this gap.  But often this results in a gap between a program that has been developed and what is written about that new program for outside audiences. 

To learn about systems, most people read manuals.  When these manuals lack clarity or are not written in a language appropriate for the reader, the innovative work of the programmer may not be recognized.  The industry loves to invent new terms, and it's tough for a practitioner, let alone a layperson, to understand the gibberish used in most trade magazines today.

Technological skill is thus not sufficient for success in this field.  If faculty were to rate students in the program on a scale of 1 to 10, the student who rates a 5 or higher in programming but only a 3 in writing is less likely to be successful than the student who rates a 3 in programming but a 5 or higher in writing. 

Typical Writing Assignments

Assignments vary by course: 

• Research papers (real research, not read and regurgitate) are required in CIS 333.
• CIS 422 & 424 require numerous types of writing, including user manuals, review of systems or journal articles, feasibility studies and numerous diagramming techniques.  There is a big emphasis on documentation of the entire life cycle of software, from concept to design and application.  In short, both written and verbal communication are imperative in the quest for quality software system design; thus students are held accountable for their writing.

Qualities of Good Writing

High-quality writing is essential to document the design process; without documentation, software implementers are not able to do their work successfully.  Good writing comes from a clear understanding of the concepts; ambiguity creates significant problems. 

Consequently, good writing is spell checked, grammatically polished work that clearly and effectively conveys the point without being verbose.  It avoids slang or use of non-professional language, it maintains a professional tone, and it defines terms and acronyms prior to using them.  Faculty require comments in source code also to be grammatically correct and take off points if they are not.

Appropriate Types of Evidence & Support

There are two primary ways writing is used in computer science:

• A programmer designs and implements a new program and must provide the specifications for it
• Someone who wishes to use the new program will read the specifications and manual to learn how to use it.

Proper citations are required, whether the sources are professional society and journal articles, Web resources, or personal resources.

Citation Conventions

Our industry uses the IEEE citation convention, which may be found at ieee.org. 

Special Comments

From Scott James, Professor of Computer Science & Information Systems:

I used to teach at GMI Engineering & Management Institute (now Kettering University) in Flint.  Every undergrad is required to carry out a thesis project prior to graduating.  When I would go out on thesis trips to our students' corporate sponsors, I would always ask, "What can we do better?"  The usual answer was "Teach your students how to effectively write. They may be bright, but it doesn't matter if they can't communicate with others."  I held high standards in the theses I advised and when I started teaching the capstone courses in the CIS program here at SVSU, I brought that expectation with me.  Building software is one of the most complex endeavors the human mind is capable of.  Much of the process is abstract and managed by paper.  It is critical that students learn how to effectively communicate in all forms. 

The programmer who can write both the program and the accompanying manuals or tutorials is promotable and will have many options.  The department recommends that all students take tech writing courses to develop their writing potential.  

References and Resources

Much information will be web-based.  It is essential that students evaluate the accuracy and quality of any websites used.