SDM > Artifacts

Process impact: This document defines the artifacts the team creates during your software development process. Documenting artifact types helps define the inputs and outputs of each development task. The producer/consumer matrix helps document the software development workflow.

Document Map

The relationships between the project documents and their approximate creation sequence is shown in the map below:

document map

Software Development Artifacts

TODO: Read the list of artifacts below and consider how each relates to your software development process. Adjust the definitions to fit your current process. Discuss these artifact definitions with the relevant team members. Use the list of artifacts as a checklist when planning project tasks. Refine this document over time to help improve your process.

Project kick-off:

Project proposal
This proposal, along with drafts of related documents, will be used by management to determine whether or not to authorize work on this project. A clear and precise project plan helps set expectations that will be used later to evaluate the success of the project.
Target audience & benefits
This document helps identify potential customers and their defining aspects. That helps to suggest and give weight to requirements. The list of benefits gives the sales team information on how to sell the product, and highlights important use cases and test cases.
User needs & stories
The statement of user needs captures and explains the actual desires of stakeholders in roughly their own words. What they desire is never exactly what the product provides. Documenting user needs here, independently from the SRS, helps to keep the SRS precise and makes the tasks of verification and validation more effective. This document is not an informal draft of the SRS, it is different document with a complementary purpose.
Interview notes & checklist
Planning questions for interviews with stakeholders is key to effective requirements gathering. Good requirements are needed to build the right system. These notes should be kept as part of the documentation on user needs are referred to when the software requirements specification is written or updated.

Project Reference Information:

Project overview
This file can serve as the project home page. It gives a very brief description of the project mission, scope, and goal, as well as current status and links to specific documents.
Project Glossary / Data dictionary
This is a glossary of terms defined as they are used in this project. Writing out the definitions of terms and acronyms here helps keep other documents more concise and precise. A shared glossary helps prevent misunderstandings and makes it easier for new team members to be productive.
Standard Glossary
This file as a dictionary of standard terms defined as they are used across projects. Individual projects should not need to edit this file. Writing out the definitions of terms and acronyms here helps keep other documents more concise and easy to edit.
Software development method
This document and its attached worksheets describe the software development process that is being used on this project. Having a defined software process helps us coordinate our myriad activities and allows us to make real improvements over time.
Project document xref
This document defines the artifacts the team creates during your software development process. Documenting artifact types helps define the inputs and outputs of each development task. The producer/consumer matrix helps document the software development workflow.

System requirements:

SRS
The SRS precisely defines the software product that will be built. Decisions made while writing the SRS are based on information in the project proposal and user needs documents. The SRS sets requirements that must be satisfied by the system design. The SRS will be validated through activities outlined in the QA plan.
Use case suite
A use case suite is simply a table of contents for the individual use cases. Much like a test suite, organizing the suite of use cases by priority, feature area, actor, business object, or release can help identify parts of the system that need additional use cases.
Feature set
A feature set is simply a table of contents for the set of feature specifications. Organizing the feature set by priority, feature area, actor, business object, or release can help identify missing, extra, or poorly motivated features early.

Planning:

Project plan
This plan will be used to evaluate and estimate the project schedule. Key assumptions that affect the plan should be documented here. Individual work items should be assigned and tracked in an issue tracking tool. The project plan should be updated throughout the lifetime of the project.
Resource needs
Based on the project plan and the worksheet below, this project will need the following resources to meet its goals. If fewer resources are available, the plan for the release should be reconsidered or the process changed.
Risk management
This document records the major risks to the success of the project and strategies for controlling them. Thinking through risks in the planning phase can help you think of ways to improve the plan. The risk map helps project members identify the most important risks at a glance. A risk can be mitigated by actions that reduce its likelihood or impact: moving it from red toward green. This document does not cover risks to users.
Legal issues
This document outlines legal issues that may affect this release. Failure to carefully consider these issues may create a risk of legal action or limit future negotiations or legal defenses.

Design:

Design overview
This design document describes a system that will satisfy the requirements of the SRS. Decisions made in creating this design document are based on those requirements and an understanding of available technologies and components. Once the design has been drafted, work on the system implementation and unit testing may begin.
Architecture
Architecture is a high-level design specification that deals with software components and connectors rather than with individual objects. The system's architecture document specifies how the system is broken down into components and how those components may be allocated to different hardware servers. Architectural scenarios give examples of how components interact, e.g., during system start-up and shut-down. Architectural goals are selected and the architecture is evaluated in terms of those goals.
Persistence
The system's persistence design contains the database schema as well as file formats and other aspects of data storage as needed. Design goals are selected and the persistence design is evaluated in terms of those goals.
User interface
This user interface design document starts with high-level decisions about the UI metaphor and the choice of appropriate UI style guidelines. The core of the UI design is a list of screens with a detailed description of the contents and purpose of each screen. Usability goals are selected and the user interface is evaluated in terms of those goals.
Security
This design document specifies how the system will achieve its security requirements. Unlike many of the other documents, this perspective on design cuts across software components. Security goals are selected and the system is evaluated in terms of those goals.
Source organization
Source code organization is usually not visible to customers, but it definitely affects our ability to productively develop the system, apply certain development tools, automate the build and packaging process, and train new team members. This document outlines our source code organization and automated build targets. Goals are set for some internal process qualities and the design is evaluated with respect to those goals.

Project tracking:

Status report log
This is a log of project status reports. It can simply list status reports in chronological order. Or, it can organize them in a way that helps visualize project trends.
Frequent status reports help keep stakeholders informed of project status so that they may correctly set their expectations. Reasoned explanations of small changes in schedule are much better than major unexplained slips later.
Review meeting log
This is a log of review meeting reports. It can simply list review reports in chronological order. Or, it can organize them in a way that helps visualize review coverage and trends.
Review checklists
Review checklists are used during review meetings to check for common errors. For example, when reviewing C code, one common error is the accidental use of = rather than ==. Many simple errors can be caught by static analysis tools (e.g., lint), but more subtle errors can only be caught by human review and understanding.

Quality management:

QA plan
This document specifies quality goals, selects strategies for assuring that those goals are met, and details a plan of action to carry out those strategies.
Test suite
This is a test suite for manual system testing. It is just one activity in the overall QA plan. A test case suite is simply a table of contents for the individual test cases. Organizing the suite of test cases by priority, feature area, actor, business object, or release can help identify parts of the system that need additional test cases.
Test run log
This is a test run log for manual system testing. A test run is logged whenever the manual system test suite is carried out. The log overview helps visualize the set of system configurations that have been tested and those that have not. Clearly understanding the degree to which the system has been tested helps to assess progress, assess risk, and focus ongoing testing efforts.

Product content:

Release notes
Release notes inform customers of what has changed in this release, as well as known problems and work-arounds.
Installation / Quick-start
The Installation / Quick-start document gives users step-by-step instructions on how to install the product and begin to use it.
User Guide
The User Guide is the main end-user documentation: it fully explains how to use the product.
FAQ / Troubleshooting
The FAQ (Frequently Asked Questions) and Troubleshooting document helps end-users quickly answer common questions and deal with common problems. The goal of the FAQ / Troubleshooting document is to help users help themselves, rather than relying on out technical support.

Product support information:

Implementation notes
This document is a brief and fairly technical discussion of how the system works under ideal conditions. It is also known as a "theory of operation" document. It should describe key algorithms, technology dependencies, and operational issues. Much of the content of this document can be drawn from design documents. This document will be used by the QA, technical support, and operations groups. The goal is to give those groups the information that they need to understand, manage, or begin to troubleshoot the system (i.e., recognize certain behavior as normal or abnormal).
Demo script
The demo script is used by sales engineers when demonstrating the product to potential customers. Multiple demo scripts may be used to address the interests of different types of customers. Each demo script is organized around key points that are expected to influence the purchase decision. Product managers and sales engineers update this document for each new release or when experience with customers identifies a need for improvements.

Release end-game:

Release checklist
The process of working through this checklist helps uncover any remaining concerns before the release, and reminds internal stakeholders of their upcoming responsibilities. Once this checklist has been satisfied, this release may be sent to manufacturing and sold to customers with the full support of the organization.
Postmortem report
This postmortem report summarizes the successes and failures of this project, lessons learned, reusable project bi-products, and recommendations for future process improvement. It is written as a joint effort by all team members, and read by (some of the same) team members when working on future projects.

Artifact Producer / Consumer Matrix

Read By \ Written By Everyone Project Manager Product Manager Dev Group QA Group Tech Writer Tech Support Operations Sales Engineer
Everyone Release-checklist, SDM Overview, Proposal, Plan, Risks SRS Mock-ups, Prototypes, Working product User guide, Release-notes
Project Manager Status-report Resource-needs, Legal Review-report QA-plan, Test-runs, Defect reports Support issues Customer feedback
Product Manager User-needs Support issues Customer feedback
Dev Group Task assignments Design QA-plan, Test-runs, Defect reports
QA Group Task assignments Design, Status-report QA-plan, Test-suite, Defect reports FAQ, Install Support issues
Tech Writer Task assignments User-needs Design-UI Support issues Customer feedback
Tech Support User-needs Design-UI Support issues Customer feedback
Operations Engineer Design-architecture, Implementation-notes Install
Sales Engineer User-needs, Demo-script Implementation-notes Install Demo-script
TODO: Check for words of wisdom for additional advice on this template.
Company Proprietary
Copyright © 2003-2004 Method Labs. All rights reserved. License terms. Retain this copyright statement whenever this file is used as a template.