an overview of software documentation

An Overview of Software Documentation

Presented to Senior Design ClassFebruary 13, 2008

Agenda

• Defining Software Documentation• Why document anything?

• Engineers, who are your customers?

• Classic Software Engineering concepts & processes

• Example document templates

• Other software documentation methods

Resources – right-click over hyperlinks to copy or open

• Book Practical Support for CMMI-SW Software Project Documentation, Land & Walz, John Wiley and Sons, 2006

• Mozilla.org website to view latest checkins for today• Development Strategies page at Mozilla.org

• Sun javadoc home page (tool for extracting documentation embedded in java source code)

Customers and Perspectives

• So, tell me...

• What are you doing?

• (I need something to pick on)

• Who are you doing all this for?

• What motivates you?

• What motivates them?

• What motivates the final customer?

Uses for Software Documentation

• We want to describe• What are we building?• Why should it be built?• What should it do?• How will it be used?• Who will use it?• What problem or need does it address?• How long will it last?• Will it continue to grow or change over time?• Who knows all these things?

Uses for Software Documentation

• We want to describe• How will we answer all those questions?• How will we design ‘it’?• Does their it make sense? Do we know a

better it?• What is its design• What is our plan to build it?• What is our plan to test it?• How will we deliver it to them?• Who the heck are ‘we’, and what will all this

cost?

Marquette Engineers...

Build me a house! With a killer home theater to watch sweet movies!

Process Drives the Products

• Every project has a process• Processes are unique to organizations

• Process prescribes the ‘how we get this done’• Process prescribes products

• The finished item (a new application)• The items produced along the way

• Prototypes• Documents• Test results• Finished, installed, integrated software

Elements in Software Processes

• Steps of the process• Several models, especially:• Linear• Iterative

• Project Management• Tools to control and track work products• Testing specifications and processes• Interaction with the end customer

What I Was TaughtThe Classic Waterfall Method of Software Development:

This image is licensed under the Creative Commons

Attribution ShareAlike License v. 2.5:

http://creativecommons.org/licenses/by-sa/2.5/

• What are we building?

• How is it designed?

• What is our plan?

• How will we know it works?

• How will we fix it?

• What is its future?

This method is risky, and invites failure.- W.W. Royce, 1970

What I Was Taught

The Classic Waterfall Method of Software Development:

This image is licensed under the Creative Commons

Attribution ShareAlike License v. 2.5:

http://creativecommons.org/licenses/by-sa/2.5/

Requirements Specification

Design Specification

Development & Integration Plan

Test Plan

Maintenance Plan

Design Document Outline (Part 1)

• Introduction • Design Overview • Requirements Traceability Matrix

• System / Architectural Design • Chosen System Architecture • Discussion of Alternative Designs • System Interface Description

Design Document Outline (Part 2)

• Design Components• Component n • Component n+1

• User Interface Design• Description of the User Interface

• Screen Image • Objects and Actions

• Supporting MaterialFrom IEEE 1016 Standard for Software Design Description

Software Documentation Standards

• IEEE standards:

• IEEE Std 830 – Recommended Practice for Software Requirements Specifications

• IEEE 1016 – Recommended Practice for Software Design Descriptions

• IEEE 829 – Software Test Documentation

• IEEE 1074 – Standard for Developing Software Life Cycle Processes

IEEE Standards Documents

• Acquisition Strategy Checklist• Baseline Change Request• CCB Charter• CCB Letter of Authorization• CMMI Work Products• ConOpsDocument• Decision Matrix• Inspection Log Defect Summary• Inspection Report• Interface Control Document• Lessons Learned• Open Issues List• Process Appraisal Checklist• Risk Management Plan• Small Software Project Management Plan• Software Acquisition Plan• Software Configuration Plan• Software Design Document• Software Measurement and Metrics Plan• Software Project Management Plan

• Software Quality Assurance Plan• Software Requirements Management Plan• Software Requirements Specification• Software Test Plan• Software Transition Plan• Software Users Manual• SQA Inspection Log• Stakeholder Involvement Matrix• Supplier Checklist• Supplier Performance Standards• System Integration Test Plan• System Integration Test Report• System Requirements Specification• System Test Plan• Training Log• Training Plan• Training Request Form• Unit Test Report

Software Document Reviews

• How are these documents agreed upon?

• What is the first review process that

comes to mind?

• Process Example: High Impact Inspection

High Impact Inspection

• Before the review meeting

• Draft document is produced

• Author (or review facilitator) selects review

team

• Draft distributed to team, date set for review

meeting

High Impact Inspection

• Before the review meeting:

• All reviewers read document, compile issues

• Issues sent to author by due date

• Author creates written response to each

High Impact Inspection

• At the review meeting:• Review each submitted issue, and author’s

response

• Document is then:• Accepted as is

• Accepted with further revision required

• Required to undergo additional review

Organizational Issues

• Training• Consistency• Culture• Productivity

Other Takes on Software Documentation

• Javadoc tool from Sun/** * Returns an Image object that can then be painted on the screen. * The url argument must specify an absolute {@link URL}. The name * argument is a specifier that is relative to the url argument. * <p> * This method always returns immediately, whether or not the * image exists. When this applet attempts to draw the image on * the screen, the data will be loaded. The graphics primitives * that draw the image will incrementally paint on the screen. * * @param url an absolute URL giving the base location of the image * @param name the location of the image, relative to the url argument * @return the image at the specified URL * @see Image */ public Image getImage(URL url, String name) {

try { return getImage(new URL(url, name));} catch (MalformedURLException e) { return null;}

}

Other Takes on Software Documentation

• Javadoc tool from SungetImage

public Image getImage(URL url, String name)

Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument. This method always returns immediately, whether or not the image exists. When this applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.

Parameters:

url - an absolute URL giving the base location of the image

name - the location of the image, relative to the url argument

Returns:

the image at the specified URL

See Also:

Image

Other Takes on Software Documentation

• What’s going on at Mozilla?• Let’s see the latest checkins for today

The GasDay™ Project at The GasDay™ Project at Marquette UniversityMarquette University

Ronald H. Brown, Ph.DAssociate Professor, Dept. of Electrical & Computer Eng.

Director, GasDay™ ProjectPhone: 414-288-3501Fax: 414-288-5579Email: ron.brown@marquette.edu

Thomas QuinnAssistant Adjunct Professor, Dept. of Electrical & Computer Eng.

Director of Sales and Marketing, GasDay™ ProjectPhone: 414-288-6201Fax: 414-288-5579Email: tom.quinn@marquette.edu

www.gasday.com