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:

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 |
Company Proprietary