Writing in Computer Science at Colby
Effective communication skills are critical to a rewarding career in computer science, no matter what kind of job you have. The computer science department at Colby has a Writing Enhanced Curriculum designed to support students as they improve the communication skills they will need to succeed beyond Colby.
Writing within the discipline of computer science has a wide variety of types and audiences, and, consequently, as broad set of characteristics. Below, we describe 15 characterstics of writing in computer science, organized in three sections:
Academic and professional writing in computer science is
- Readable: A reader with the appropriate background should be able to comprehend the meaning of the text and graphics with relative ease.
- Clear in Purpose: It should be clear to the reader why it is profitable to read the document. For example, it may contribute to an area of research or teach someone how to use a new programming language.
- Well-organized: states the overall purpose in the beginning, then uses a logical flow of ideas (e.g. theoretical statements or mathematics) and information (e.g. data) to fulfill the purpose.
- Concise: written for fast comprehension. There are few words, but not so few that it is difficult to follow the reasoning.
- Graphical: Well-designed figures should be used to summarize concepts that are best displayed graphically, e.g. process, design, and data. Well-designed figures display these concepts with the minimum amount of information necessary to make the desired point. For figures displaying data, there is also enough data for the reader to be able to draw their own conclusions about the data. Figures should be used to allow for fast comprehension of the data but should not hide confounding features of the data. Figures should be labeled well.
Broadly speaking, we identify five types of writing in the field:
- Persuasive: Depending on the type of document, it should persuade the reader to take action (e.g. follow-up on action items), support the work of the writer (e.g. proposals), appreciate the work of the writer (e.g. being persuaded that the writer has interesting and correct research results), or use a piece of software (e.g. a user guide or technical blog).
- Descriptive: Descriptive writing, such as presenting a process, algorithm, or the output of these, should give the user an accurate sense of the purpose, workings, or function of what is being described. Descriptive writing may also explain the source or process by which data has been obtained or manipulated in order to achieve a certain result.
- Explanatory: Explanatory writing attempts to communicate to the reader a new concept or process. One example of explanatory writing is tutorials. In code, descriptive writing explains the functionality of code, while explanatory writing covers why the code is important.
- Analytic: Analytic writing describes the examination, subdivision, or proof of a concept, process or data. In computer science, these could include an analysis of time or space complexity, proof of correctness, or an examination of typical or pathological cases.
- Code: code should follow the same characteristics as natural language: readable, clear in purpose, well-organized, and concise.
At the more detailed level are additional, specific writing skills. Writing in computer science should be:
- Audience-specific: Take into account the interests and background of the intended reader (e.g. a software user who wants to learn how to interact with the GUI or a peer in the course who is interested in implementation details). For example, for non-technical audiences, the writing should be free of jargon.
- Grammatically Correct: English usage and grammar should follow widely accepted rules, such as those in the Pocket Style Manual by Hacker and Sommers.
- Well-documented: Code should have comments that make it straight-forward for another programmer to maintain it.
- Appropriately and properly referenced: proper references to other papers/documents. This includes proper references to authors/sources for code.
- Multi-modal: Posters and oral presentations are commonly used modes of communication and they need to have the same characteristics as written documents. In particular, they need to make a clear point and make it quickly.
Students graduating with a major in the computer science department should be able to:
- Create precise descriptions of processes, data, and/or findings such that readers are able to quickly understand and are persuaded by the presentation.
- Explain processes and concepts to a target audience for the purpose of teaching or instruction
- Write an analysis or critical evaluation of a design, concept, algorithm, findings, data, or process
- Write concise, precise, easy to read code so that it can be easily maintained
- Write concise, easy to read, well-documented comments or documentation so that the code can be used by others
- Be able to integrate text, code, and figures into a comprehensive and smoothly flowing document so that the reader can understand the content better or faster than they would with text alone
- Effectively present written work in different forms--papers, posters, short talks, longer talks
- Properly cite sources (e.g. peer consultation, images found on the internet, publications, web pages)
- The writer uses an effective voice to describe his/her processes, tests, and choices so that the reader is easily engaged