Introduction
and Overview
Fall 2001
Edition
Table of Contents
This document provides an overview of the documentation
standards to be used in CMPS 374 Fundamentals of Software Engineering, CMPS 490
Computer Projects and the thesis requirement for the Master of Science in
Software Engineering degree. It also covers documentation for internships
(proposals and final reports).
Any comments or corrections should be addressed to the
author: Dr. Dennis S. Martin, Computing Sciences Department, University of
Scranton, Scranton PA 18510-4664, martin@scranton.edu
The computing sciences do not have as strict a set of
standards for the production of documents as, for example, the Modern Language
Association (MLA), but it does have guidelines developed over many years to
ensure that documents and code are readable and complete.
This document is based on several recommended standards
(noted in section 1.4) and is to be regarded as an advisory standard for use
when appropriate in the department. It is the latest version of a series of
documentation standards developed by the author (and others) for use in CMPS
374, CMPS 490, and the Master’s thesis requirement and replaces all of those
previous standards. Suggestions about how to perform the technical aspects are
for Microsoft Word.
This document is intended for use at the University for all
projects within the Computing Sciences department. The main audience is the
developers of documentation for such a project. A secondary audience is faculty
members who need to give guidance to students engaged in such endeavors. An
additional audience is faculty at other institutions that wish to enhance
documentation standards at their schools. Please see the copyright notice
above.
These standards are to be used as guidelines rather
than straight jackets. One size does not fit all! However, when a student
diverges from these standards, it is the responsibility of the student to
ensure that the purpose of the standard is still met. This document includes
the reasons for each requirement.
The concept of documentation involves two distinct but
closely related activities — implementation (program) documentation and project
documentation.
The Software Development Life Cycle (SDLC) involves a number
of phases, each of which should produce properly documented artifacts. Although
different authors describe the stages differently, they all include:
·
Investigation
·
Analysis
·
Design
·
Testing
·
Implementation
·
Maintenance
The Implementation Phase documentation standards specify how
to properly document the implementation artifact, i.e., the code. This includes
proper documentation for a program, class, method and package as well as naming
conventions for user-defined entities in code. This document does not
explicitly cover such documentation. The reader is referred to the emerging
standards for documenting APIs by Sun Microsystems for a good set of standards
[http://java.sun.com/docs/index.html].
The other phases produce mostly written artifacts. These
include the
·
Proposal Feasibility Document
·
Proposal Justification Document (a.k.a. Business Case)
·
Gantt Charts
·
Specification Document (Software Requirements
Specification)
·
Design Document (Software Design Description)
·
Test Design Document
·
User Manual
·
System Reference Manual
At the University, the first three correspond to our
Proposal requirement (see below for variations for different courses). The
others form individual documents. All are described in this document. In
addition, there is a section detailing the format standard to be used for a
master’s thesis.
|
Term |
Definition |
|
Configuration Management |
Version control. Versions of various documents must be
consistent. |
|
Design |
A document that shows the architecture of the system and
the assignment of its components to physical nodes. Each component is fully
detailed to answer any question that the implementers may have about the
product to be created. |
|
Feasibility |
The property that a project is possible to be built by the
proposing team. Some factors to consider are the state of the art in software
development, the tools available and the skills of the development team. |
|
Functionality |
One of the behaviors that the system exhibits. Also used
as a collective noun to describe all the functionality of the system. |
|
Gantt Chart |
A graph showing the planned development of the system in
terms of time allotted for each task. |
|
Justification |
The propriety that a project is cost-effective to build.
This is used to decide which of several possible projects should be the one
that is continued. |
|
Maintenance |
A continuation of the software development process to
correct errors (corrective), change elements of the environment (adaptive) or
add functionality (perfective). |
|
Process |
A paradigm (methodology) for producing a project. Examples
are the Waterfall Paradigm, the Unified Software Development Process or
Rapid-Prototyping. |
|
Product |
Any of the artifacts of a project. It may be a document,
source code, an executable module or any other physical entity generated
during a project. When not otherwise stated, product refers to the completed system itself. |
|
Project |
A software development activity. It includes process and
product. |
|
Proposal |
A document which outlines the project to be developed. It
is less detailed than the SRS but gives sufficient detail to estimate the
feasibility of the project and whether it is cost-effective to proceed
(justified). |
|
SDD |
Software Design Description (see Design) |
|
Specification |
A document explaining all of the functionality and
environment of the product. It is readable by the user to ensure that the correct
product is being build (Validation). It is detailed enough to test whether
the product built meets its specifications (Verification). |
|
SRS |
Software Requirements Specification (see Specification) |
|
System Reference |
A document designed to be the foundation for all
maintenance. It includes the SRS, SDD, Test Design, User Manual and
information about the current state of the project. |
|
Test Design |
A document written for the system developer to ensure that
the product is as error-free as possible. It includes testing strategies and
testing result-recording procedures. |
|
UML |
Unified Modeling Language — a graphical standard for use
in documenting software development projects developed by Jacobson, Booch and
Rumbaugh. |
|
USDP |
Unified Software Development Process — a paradigm to
create software systems developed by Jacobson, Booch and Rumbaugh |
|
User Manual |
A document written for the user of the system to show normal
usage, to explain how to use the help system and to detail all messages given
by the system. It may include installation instructions. |
|
Validation |
The process that ensures that the correct product is being
built. |
|
Verification |
The process that ensures that the product built meets its
stated requirements and is error-free. |
Braude, Eric. Software Engineering: An Object-Oriented
Approach. Wiley, 2001.
IEEE, Software Engineering, 1999 Edition, Complete
4-Volume Set, Institute of Electrical and Electronic Engineers, Inc., 1999.
[Selected Contents:
Volume 1: Customer and Terminology
Standards
·
610.12-1990 IEEE Standard Glossary of Software
Engineering Terminology [Description] (Revision and redesignation of IEEE Std
729-1983)
·
1229-1998 IEEE Standard for Application and Management
of Systems Engineering process (discusses planning)
·
1233, 1998 Edition IEEE Guide for Developing System
Requirements Specifications
Volume 2: Process Standards
·
1008-1987 (R1993) IEEE Standard for Software Unit
Testing
·
1012-1998 IEEE Standard for Software Verification and
Validation
Volume 3: Product Standards
·
1063-1987 (R1993) IEEE Standard for Software User
Documentation
Volume 4: Resource and Technique
Standards
·
829-1998 IEEE Standard for Software Test Documentation
·
830-1998 IEEE Recommended Practice for Software
Requirements Specifications
·
1016-1998 IEEE Recommended Practice for Software Design
Descriptions]
(see also
Moore, James W. Software
Engineering Standards: A User’s Road Map. IEEE, 2000.)
[These guidelines are available in
the second floor Reserve Room of the Weinberg Memorial Library under QA76.758
.I113 1999 v1-v4]
Jacobson, Ivar, Grady Booch, and James Rumbaugh. Unified
Software Development Process. Addison-Wesley, 1999
Kulak, Daryl and Eamonn Guiney. Use
Cases: Requirements in Context. Addison-Wesley, 2000.
Scott, Kendall. UML
Explained. Addison-Wesley, 2001.
Stiller, Evelyn, and
Cathie LeBlanc. Project-Based Software Engineering: An Object-Oriented
Approach. Addison-Wesley, 2002.
Sommerville, Ian. Software Engineering, Sixth Edition. Addison-Wesley,
2001.
Example documents in departmental library and online include
Martin, Dennis
S. Mathematics Placement System 2.0.
University of Scranton, 1999.
{Contents:
Mathematics Placement System 2.0, Sabbatical
Proposal.
Mathematics Placement System 2.0, Software
Specification Requirements.
Mathematics Placement System 2.0, Software
Design Description.
Mathematics Placement System 2.0, Test
Design.
Mathematics Placement System 2.0, User
Manual.
Mathematics Placement System 2.0, System
Reference Manual.]
Moffitt, Daniel and Raymond
Schafer, Robert Steffenauer, and George Toretta. Registration Forecast
System of the Dexter Hanley College. University of Scranton (Fundamentals
of Software Engineering), 2001. (Referred to as the SE Team in this document).
In addition, a large selection of the CMPS 374 projects and
some from CMPS 490 developed using versions of these standards over several
years is available for study in the departmental library. Not all of these
follow the standard exactly as all were part of the developmental process. In
particular, there is much variety in the Spring 2000 projects as the students
were encouraged to try various interpretations so that the author could see
which seemed to work best. Remember that these standards are guidelines and
an alternative format may be a better way to proceed for a particular project.
In addition, the following URLs are important:
CMPS 490:
http://www.cs.uofs.edu/~plishka/cmps490/cmps490.html
Thesis Project: http://www.cs.uofs.edu/~se/
The following case studies are available from the text Web
site:
http://www.wiley.com/college/braude
(The files are html files available in zipped format.)
The reader should look at them as
we cover the related documents. This project is very different from the example
projects that I have provided. In addition, there are documents above that I do
not cover and I cover documents that Braude does not.
Note that Braude interprets a
number of the IEEE categories differently than I do. In this class, use my
interpretations but be aware of the differences. A firm that prefers the
interpretations of Braude may hire you.
Please note that, due to evolving requirements of the
standards, not all of the examples shown or referenced in this document
completely meet the guidelines of this document. They should still be studied
because they met the standards in place at the time; they are effective
alternative ways to meet the requirements; and the standards contained here are
guidelines and alternative formats may be more appropriate in certain
circumstances.
Please also note that all text in this document is single-spaced
even when quoting from the double-spaced example documents. A thesis is
double-spaced by University requirements. All of the other documents required
by various courses in our department are double-spaced to allow faculty to
write comments during document review.
This document presents the documentation appropriate for a
software development project for all phases other than the implementation
phase.
The next section covers general
formatting guidelines for all of the documents beyond the proposal.
The third section explains the role
of the Use-Case as a fundamental entity in assuring that the correct product is
created (validation).
Separate major divisions of this document
follow on the proposal (including feasibility, justification and Gantt charts),
software specification requirements, software design description, test design,
user manual, system reference manual and the thesis requirement.
The Appendix contains information
on how to obtain and use the UML and some of the templates for documents. (They
can be downloaded from the electronic version of this document.)
I have often been curious about the statement that “by our
students we are taught.” This is not a belief that I held early in my career as
I was hired as a specialist to pass on specialized knowledge to students. That
is why they pay and I get paid. It took me a long time to appreciate the fact
that my job was not as much to implant knowledge into students’ minds as to
teach students how to learn. What I teach is a foundation to build on rather
than the final structure. When I started to teach students to document, I
discovered that I was trying to teach a process that I was not really a master
of myself. I had available guidelines developed by my colleagues and used
previously in the projects course but these were informal and only a starting
place for this work.
I wish to express my appreciation to many students over many
years that have contributed to the quality of this document by their reactions
to my attempts to show them how to document. Their questions and comments as
well as their work have enabled me to understand this process better. If this
document is useful, it is because they have shown me how to do better.
In particular, I want to thank all those students whose
senior projects and masters' theses I have advised. I have learned much from
you. My greatest teachers have been my students in CMPS 374 Foundations of
Software Engineering. Over the years you have forced me to reconsider
everything that I thought that I knew about writing. In particular, the Spring
2000 class has helped me to integrate the UML into these documents. As this is
a work in progress, future students will also help to improve it. Send in those
comments!
I particularly want to thank the following students who have
allowed me to use as examples in these documents work that they developed.
Thanks to Maureen Brady (The Testing Assistant) and Peter Maroon (Inventory
and Work Order Management System – IWOMS) for work during their Computer
Project class in Fall 2000 and the team Daniel Moffitt, Raymond Schafer, Robert Steffenauer, and George
Toretta for their work in Software Engineering in Spring 2001 (the SE Team in
this document).
The work for
Computer Projects owes much to its instructor, Professor Richard Plishka. The
work for the Master’s project owes much to the director of our Software
Engineering graduate program, Dr. Yadong Bi.
Thank you all.
© 2001 by Dennis Martin
Branch to the Project Documentation Standards Homepage