Download - 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: [email protected]
Thomas QuinnAssistant Adjunct Professor, Dept. of Electrical & Computer Eng.
Director of Sales and Marketing, GasDay™ ProjectPhone: 414-288-6201Fax: 414-288-5579Email: [email protected]
www.gasday.com