Writing in Computer Science

by Ian Cook, July 7th, 2011





1 Introduction
2 Technical Writing
3 Documentation
   3.1 Project Proposals
   3.2 POS
   3.3 SPMP
   3.4 SRS
   3.5 SDS
   3.6 STS and STR
   3.7 User Manuals
   3.8 Code Comments
   3.9 Memoranda
4 Citation Styles
5 Additional Resources
6 Reference

1 Introduction

I am an undergraduate at CSUS studying Computer Science.  I'm in my senior year as of this writing and I want to briefly cover the different writing styles and documents generally found in Computer Science.  My purpose is to highlight some of the typical expectations for writing in the major and to describe the most commonly used documentation types.  Hopefully, this will give newcomers to the major an introduction to the kinds of writing that is required.

I didn't encounter much writing in the major until my senior year.  The majority of my writing experiences came from required General Education classes, like: English, History, and Philosophy.  These classes teach us the basis for academic writing such as: expository writing, personal essays, research papers, and argumentative writing.  All are valuable writing styles which we will surely use throughout our careers.  However, missing is the most common form of writing used in software engineering and computer science: technical writing. 

During our senior year, all Computer Science majors are required to complete a senior project.  The Senior Project is a two semester capstone course that is designed to give students actual experience in developing a real world software project.  During the course project teams plan, design, implement, and test a software application for an actual sponsor.  Sponsors can be companies or individuals who have a specific need for a software application.  The student teams work closely with their sponsor over the course of a year in order to develop software that meets the sponsor's needs.  Major components of these projects are various technical documents which serve different purposes throughout the development process.  Project development is divided into a series of phases.  For example, there is an initial project overview phase, a project management planning phase, a software requirements specification phase, and so on.  Each of these phases culminates in a technical document which specifies the details of that phase.

I asked Prof. William Mitchell, a Computer Science Senior Project advisor, to compare the writing found in the project courses (CSc 190 and 191) to writing found in the Computer Science industry:

"‘190/191 writing’ (aka SenPr) is a GOOD overview of the basics of life cycle documentation. However, realize that it is an OVERVIEW of this area. SenPr is the first time that many (not all, but most) students have dealt with a project lasting more than the 2 to 3 weeks duration of a ‘homework’. Homework is unrealistic in that projects are the work unit in the real world, so much so that you might spend part of your job description for 2+ years on the same project/app in real world, but of course this depends on where you work."

The project is intended to simulate the documentation and project management practices required for a typically large multi-year real world project.  This gives students an opportunity to experience practical project development which otherwise wouldn't be possible in an undergraduate academic setting.

The style of writing in these documents is quite different from what I was used to in my previous writing classes.  The writing is not difficult; however is it useful to know a few guidelines before writing a technical document.

In the next two sections I will describe some aspects of technical writing as well as introduce the various document types used in Computer Science.


2 Technical Writing

Technical writing is a style of writing used in scientific or mathematical fields in which clear and concise descriptions, explanations, or instructions are needed.  From the Mayfield Handbook of Technical and Scientific Writing

"Good technical communication is accurate, clear, concise, coherent, and appropriate. In the prose of science and technology, these qualities are sometimes difficult to achieve. Not only do science and technology depend heavily on specialized concepts and terminologies, but they also make extensive use of numbers and graphics." [1]

Technical writing is a form of direct clear communication.  The main purpose of the style is to inform or explain.  There should be no hidden meanings or innuendos for the reader to interpret.  The writer's intended purpose should be defined and clearly stated towards the beginning of the document.   

The writing should be directed at a specific audience and the writer should understand to what purpose the audience will be using the writing.  If the target audience consists of expert engineers then basic concepts may not need to be explained.  On the other hand, if the writing is a user's manual intended for a more general audience then step-by-step instructions will need to be elicited.  The audience will determine the level of detail needed for the document.

Organization is important in technical documentation.  Large documents are not meant to be read from cover to cover.  Readers may only need to read specific sections within the document.  Documents should be organized such that section headings are numbered and easily accessible via a table of contents.  Each section and subsection should be clearly mapped out in the beginning of the document.  Readers should not have to dig or hunt for the information that they are seeking.

Technical writing also makes heavy use of tables, charts, and figures in order to organize and display information.  These should be clearly labeled and referred to within a section.  As in, (see Figure 1) or (see Table 1.1).  It is ineffective to insert a table without giving some explanation in a caption or the text.  Appendices can be used if large amounts of figures are needed.  A writing guide from Colorado State University states that:

"Appendices include information that is too large to fit within your report, yet information necessary to your report. For example, large graphics, computer print-outs, maps, or sample codes are best placed in Appendices. When making decisions about what to place in an Appendix, consider whether or not the material interrupts the reading flow. For instance, six pages of calculations would obviously cause readers to loose their train of thought. Appendices always appear at the end of a report." [2]


Things to avoid include using passive voice.  Voice is the way the subject of a sentence is related to the action of the verb.  Voice can be passive or active. Prof. Buckley, CSUS senior project instructor, gives an example:

        PASSIVE: The selection of this operation is made automatically by the software if there is no intervention by the operator.

        ACTIVE: Unless the operator intervenes, the software selects this function automatically. [3]

In the active case the subject (software) is doing the action (selecting).  While in the passive case the subject (selection of the operation) is being acted upon (made) by the software.

Active voice is much more clear and direct.  Other things to avoid are using pronouns like, he or she, as much as possible.  Instead use a more neutral approach. 

        For example:
        Once the user installs the program, he will need to reboot the system.

        This can be written as:
        After the program is installed, the user will need to reboot the system.


Also, do not use colloquialisms or cultural references.  Technical documents may be read internationally.  Non-English or non-native speakers may not understand local references, humor, or sarcasm.  Use standard English in order to make your writing clear.

The following links provide more detailed guides to technical writing: 

The next section will introduce common types of documents used in Computer Science.

3 Documentation
There are many documentation types found in the Computer Science industry.  Covering each of them is beyond the scope of this writing.  However, it is important to understand that many of the documentation types will follow a certain format or standard.  Always check with your company or client to verify the required format.  I will briefly introduce the main types of documents used in the Sacramento State Computer Science Senior Project.

3.1 Project Proposals

Project proposals are used to introduce projects to clients or management.  They identify a specific problem and state how that problem will be solved. [4]  

The purpose of the proposal is to convince your audience that you have a viable solution to a specific problem.  Proposals should briefly describe the nature of the client's business and what the client's needs are.  Then describe how the software will meet those needs.  The level of detail needed will be dictated by the size of the project, but proposals should be rough estimates of possible projects.  Proposals for small projects may be very brief, a page or two, while proposals for large expensive projects will need to be much more detailed and thorough.  A refined description of the project will come in future documents.


 Click figure for an example.

Example Project Proposal [5]


3.2 Project Overview Specification (POS)

A POS is the first step in refining the project described in the proposal.  The purpose here is to provide an overview of the project to the client.  The intent is to create a mutual understanding between the development team and the client of what is expected over the course of the project. [6]

The main sections of the POS include an executive summary of the document, followed be a description of the client and the client's needs.  This serves to let the client know that the development team understands the client's business and provides a clear statement of what the problem is.  The POS also defines the goals and vision of the project.  In general terms it should describe how the project will fulfill the client's needs.  The POS will introduce how the project will be managed and include an estimated schedule and budget.  Finally, the POS concludes with a listing of assumptions and constraints that may limit development.  Constraints can include time, cost, or technical limitations.  It is important to define constraints in order establish the project's scope and final expectations.  Without limiting factors the project may never finish.


3.3 Software Project Management Plan (SPMP)

The SPMP is used to describe the development team's management process for the project.  It describes the project's organization and control processes.  This does not describe the software itself, only the processes for which it will be managed.   Things to include will be potential risks and how to deal with them, project schedules, budget, and software tools that will be used during development. [7]

The SPMP focuses on the organization of the project.  The process model should be clearly specified in order to show the flow of the project phases (see figure right).  Phases are then broken down into the necessary tasks needed to complete each phase.  Weekly schedules for each phase are set in order to ensure project progression.  The SPMP is used as a guide to control and manage the project.

 

process model
Example Process Model [7]

3.4 Software Requirements Specification (SRS)

This is where we completely define the functionality of the software.  The SRS is a refined description of the software's intended uses as well as its non-functional requirements.  Intended uses are specified with use-cases.  Each use-case describes a scenario for which a user will interact with the software.  A use-case may specify the steps needed in order for an administrator to manage users on a social networking site, for example (see diagram right).  The use-case steps must be described completely and precisely.  All possible scenarios should be defined.  These requirements will be used to determine the design of the software.

Non-functional requirements involve things like security, performance, and reliability.  The SRS serves as a kind of contract between the developers and the client detailing the intended behavior of the finished product.

Included are definitions of the data elements, data structures, or data tables that will be used in the design.  This is known as the data dictionary and should clearly define the type, purpose, and description of each element. [8]




use case diagram
Use-case Diagram

3.5 Software Design Specification (SDS) or Software Design Description (SDD)

The purpose of the SDS is to give the development team a guideline as to how the project is to be implemented.  It describes the system's architecture; how the different modules of the software will interact with each other.  Diagrams or figures are often used to provide visual descriptions of how components relate to one another.  The SDS also reveals to other developers what design decisions were made.  This makes it easier to modify or maintain the software in the future.



Example Graphical Interface (GNOME Desktop GUI)


In addition to the system architecture, the SDS specifies the interface design.  This is the portion of the system that the user will be interacting with.  It includes prototypes of how a graphical interface may look.  Multiple prototypes can be produced until a final interface layout is adopted.

Also included are detailed definitions for each component of the software.  Each component will relate to each of the use-cases previously described in the SRS.  The components will contain the actual code needed to implement those use-cases. 
 


architecture diagram

Example architecture diagram: [9]

3.6 System Test Specification (STS) and System Test Report (STR)

The purpose of the STS is to describe the plan for testing the software, and to specify the test cases and test procedures necessary to demonstrate that the software satisfies the requirements as specified in the project’s System Requirements Specification document. [10]

This provides an organized plan for the developers to follow in order to test the program thoroughly.  It also allows other developers to be able to confirm what test cases have or have not been performed.  The actual results of the test cases can be used to generate a System Test Report. [11]  The results are then evaluated to determine if the software has adequately satisfied the requirements.


3.7 User Manuals

User manuals are guides that instruct users on how to use the software.  They should include step-by-step instructions that are easy to follow. 

User manuals generally provide the following information:

Safety warnings and tips

Typical applications and capability of the technology

Descriptive system overview with illustrations

Functional description of subsystems

Instructions for operating the system

System maintenance requirements

Parts lists

Troubleshooting instructions [12]

Manuals need to be extremely well organized in order for users to locate the relevant information they are seeking. 

As an example, this is the MySQL 5.5 Reference Manual.

In addition to a table of contents, it makes use of a section navigation pane to provide users easy access to each section.  It also has a table that references main sections of the manual.  It even has a search field users can use to search for keywords throughout the entire manual.  Providing multiple ways to traverse the manual makes it easier for users to find what they need.  [13]

3.8 Code Comments

In almost every programming class here at Sacramento State University it is required to include comments with your code.  Code comments allow other developers the ability to understand the intended behavior and purpose of your code.  Other developers need to be able to understand your code in order to modify and maintain it.  Without sufficient comments this task can become incredibly difficult and time consuming. 

From the Microsoft MSDN library:

"It is a best practice that most code will have comments reflecting the developer intent and approach for the code. Use comments liberally. Include comments that indicate who made the changes, when the changes were made, why the changes were added, and what the changes do. Comments are particularly beneficial when multiple parties are involved in modifying and maintaining code." [14]

A skilled programmer can read your code and determine what the effects are, but what is not clear is the purpose or intent of the code.  It is a good idea to begin every function, procedure, or code block with a statement of purpose.

Check out this guide from suite101.com:


3.9 Memoranda

We use memoranda or memos in order to fulfill a variety of objectives.  The style and purpose of the memo will depend on your objective.  Objectives can range from an instructor wants your reaction to a journal article to a manager needs to inform the development team about a policy change.  Memos should be limited to a few pages and should have a clear purpose.  Usually the format of a memo is standardized within a company with its own heading style and letterhead. 



memo template
Example Memo Template

4 Citation Styles

There is no set standard citation style in Computer Science.  It is best to check with your instructor or employer in order to find out their preferred citation style.  Below are links to commonly used citation styles.

There are also a number of online citation generators that will automate citation formatting for you. 

Examples include:

 

5 Additional Resources

It is imperative as Computer Science professionals that we keep up with changing technology.  Information Technology is a wide ranging field; too vast for one person to be an expert in all aspects of it.  But even though we may not be working in certain areas of the field we can become exposed to them by regularly reading related journals, magazines, and books.  Reading recent publications keeps us informed about trends and new technologies that are constantly emerging.

Here are a few recommended online journals and magazines: 

  • IEEE Software - Produced by the IEEE Computer Society, it features peer-reviewed articles directed towards software professionals.
  • Dr. Dobb's Journal - Used to be a monthly journal, but is now a website that features tech news and articles. 
  • Crosstalk Magazine - Online journal directed towards software engineering in the U.S. Department of Defense.
  • ACM Queue - Published by the Association of Computing Machinery, includes software related articles and regular columns.  The online version provides audiocasts and videos of interviews with software developers.

The Institute of Electrical and Electronics Engineers (IEEE) is an organization that creates standards for scientific and engineering industries.  Standards provide a means for uniformity in engineering practices throughout the world.  IEEE provides standards for both technical protocols and documentation.  Many of the documentation types found in Computer Science adhere to IEEE standards.  The IEEE Standards Association library can be found here: IEEE-SA 

For an in depth look at what is required for the senior project check out the Computer Science Senior Project websites:



6 References

Citations of sources used:

[1] Perelman, Leslie C., James Paradis, and Edward Barrett. "Effective Technical Communication: Characteristics" The Mayfield Handbook of Technical and Scientific Writing. McGraw-Hill Companies., 2001. Web. 20 Jun 2011. <http://www.mhhe.com/mayfieldpub/tsw/eff-char.htm>.

[2] Kowalski, Dawn. "Appendices." Writing@CSU. Colorado State University, n.d. Web. 20 Jun 2011. <http://writing.colostate.edu/guides/documents/ce-trpt/pop3i.cfm>. 

[3] Buckley, Robert. "Writing Software Documentation: Some Guidelines." Information on CSc 190. California State University Sacramento, 15 Nov 2010. Web. 20 Jun 2011. <http://gaia.ecs.csus.edu/~buckley/CSc190/WritingGuide.pdf>.

[4] Perelman, Leslie C., James Paradis, and Edward Barrett. "Proposals" The Mayfield Handbook of Technical and Scientific Writing. McGraw-Hill Companies., 2001. Web. 20 Jun 2011. <http://www.mhhe.com/mayfieldpub/tsw/proposal.htm>.

[5] Miller, Brett. "Project Proposal - Software Development - Sample." Custom Software by Preston. Custom Software by Preston, 21 Nov 2010. Web. 20 Jun 2011. <http://www.customsoftwarebypreston.com/software-development-proposal>. 

[6] Buckley, Robert. "Guide to Preparing the Project Overview Specification Document." Information on CSc 190. California State University Sacramento, 24 Sep 2007. Web. 20 Jun 2011. <http://gaia.ecs.csus.edu/~buckley/CSc190/POS.pdf>.

[7] Buckley, Robert. "Guide to Preparing the Software Project Management Plan." Information on CSc 190. California State University Sacramento, 29 Nov 2007. Web. 20 Jun 2011. <http://gaia.ecs.csus.edu/~buckley/CSc190/SPMP.pdf>. 

[8] Buckley, Robert. "Guide to Preparing the Software Requirements Specification Document." Information on CSc 190. California State University Sacramento, 2 Nov 2010. Web. 20 Jun 2011. <http://gaia.ecs.csus.edu/~buckley/CSc190/SRS.pdf>.

[9] Buckley, Robert. "Guide to Preparing the Software Requirements Specification Document." Information on CSc 191. California State University Sacramento, 13 Oct 2010. Web. 20 Jun 2011. <http://gaia.ecs.csus.edu/~buckley/CSc191/SDS.pdf>.

[10] Buckley, Robert. "Guide to Preparing the System Test Specification." Information on CSc 191. California State University Sacramento, 18 Oct 2006. Web. 20 Jun 2011. <http://gaia.ecs.csus.edu/~buckley/CSc191/sts.pdf>. 

[11] Buckley, Robert. "Guide to Preparing the System Test Report." Information on CSc 191. California State University Sacramento, 30 Mar 2005. Web. 20 Jun 2011. <http://gaia.ecs.csus.edu/~buckley/CSc191/str.pdf>.

[12] Perelman, Leslie C., James Paradis, and Edward Barrett. "User Documentation" The Mayfield Handbook of Technical and Scientific Writing. McGraw-Hill Companies., 2001. Web. 20 Jun 2011. <http://www.mhhe.com/mayfieldpub/tsw/doc-user.htm>. 

[13] Hinz, Stefan, Paul DuBois, Jonathan Stephens, Anthony Bedford, and John Russell. "MySQL::MySQL 5.5 Reference Manual." MySQL::Developer Zone. Oracle, Nov 2009. Web. 20 Jun 2011.

[14] "Top Best Practices to Consider." MSDN – Explore Desktop, Web, Cloud, and Phone Software Development. Microsoft, n.d. Web. 20 Jun 2011. <http://msdn.microsoft.com/en-us/library/cc967435.aspx>.



© Ian Cook, California State University Sacramento, 2011