Suborbital-Systems/MorseTrackerSwDocs
2
0
Fork 0
Code Pull Requests Packages Projects Releases Activity

initial readyset

Browse Source
This commit is contained in:
Charles N Wyble - admin 2021-05-13 11:28:40 -05:00
parent 97b3f146d9
commit 058e7d015e
53 changed files with 9212 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
ProductDocumentation/.vscode/settings.json vendored Normal file
View File

@ -0,0 +1,5 @@
{
"markdownlint.config": {
"MD026": { "punctuation": "?" }
}
}

180
ProductDocumentation/Demo-Script.md Normal file
View File

@ -0,0 +1,180 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Project proposal](Proposal) > [Target audience and benefits](Target-and-Benefits)
- [SRS](SRS) > [Use case suite](Use-Case-Suite)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
### Demo Planning
*TODO: Think through your goals for this demo.*
#### Who is the target audience for this demo?
- ::Investors and potential investors
- ::Potential customers
- ::Management, other developers, or partners
- ::End users as part of training
#### What is your main goal for this demo?
- ::To convince the audience to make a decision and take action. E.g., a
sales call.
- ::To inform the audience about the product and prompt
further discussions. E.g., showing another team where their product
would have to integrate with yours.
- ::To provide evidence of progress. E.g., showing your boss that you
are done with the UI.
#### What main points will you use to achieve your goal?
- ::This product automates much of the user's task, thus increasing
productivity and cutting costs.
- ::This product is very easy to use, which will encourage
rapid adoption.
- ::This product supports use cases that are key to the customer's
overall business process or that enable new
business opportunities.
- ::We have built only 4 of 10 screens, but the remaining screens
are much easier to build.
- ::We have build 7 out of 10 features, and it turns out that one of
the remaining features cannot possibly work like the others.
#### How much time is available to present the demo?
- ::10 minutes, no questions
- ::10 minutes, plus questions
- ::30 minutes, including questions
#### What equipment and setup is needed to give the demo?
- ::One person. Any computer with a web browser.
- ::One person. Any computer where we can install from CD or
the Internet.
- ::Two people. Two high-powered laptops with specific software and data
pre-installed, a wireless networking base station, and a hand-held
with a wireless networking card.
### Demo Script
*TODO: Outline the steps of the demo. Plan out what you will do and say.
Practice three times to make sure that all system features actually work
as needed, and that there is enough time.*
*TIP: Imagine that you are in the audience. Do you understand what is
being shown at each step? Is the demo too fast? Too slow? Too long? Are
you interested? What are your questions or concerns? Do you strongly
disagree with any points?*
#### ::Beginning
- ::SET EXPECTATIONS
- ::SET THE STAGE
- ::KEY POINT
- ::DEMO STEP
- ::DEMO STEP
#### ::Middle
- ::KEY POINT
- ::DEMO STEP
- ::DEMO STEP
- ::KEY POINT
- ::DEMO STEP
- ::DEMO STEP
- ::KEY POINT (if there is time)
- ::DEMO STEP
- ::DEMO STEP
#### ::Ending
- ::FINAL POINT
- ::DEMO STEP
- ::DEMO STEP
- ::CONCLUSION OR SUMMARY
- ::CALL-TO-ACTION OR NEXT-STEPS
### Anticipated Questions
*TODO: Write down a few common questions that you expect to be asked, and
good answers.*
*TIP: You can leave some less critical points out of the demo and only
use them if someone asks a question.*
#### ::How does this compare to OTHER-PRODUCT?
::ANSWER
#### ::What happens if you do X or Y?
::It would do Z.
#### ::When will your product be ready?
- ::We have announced a release date of July 17th.
- ::We are planning a release this Winter, but no specific date has
been set.
- ::We have not announced a release date yet.
### Demo Checklist
*TODO: Use the following questions to help you evaluate your demo.*
#### Are you making the right points in the right order?
::Yes, we feel that we will accomplish our goals.
::No, we need to better prioritize our points.
#### Can it be presented in the available time?
::Yes, we could even add more or finish early.
::Yes, we have optional sections that can be skipped to save time
if needed.
::No, we need to make the same points more quickly or make
fewer points.
::No, we need to change the available time.
#### Do all system features actually work as needed?
::Yes, everything is finished and working.
::Yes, there are defects, but they will not matter for this demo.
::Don't know, we need to plan alternative demo steps just in case
something fails.
::No, we need to quickly fix the system and/or change the demo to make
our points without exposing defects.
#### Does the demo end effectively?
::Yes, viewers will be satisfied and convinced.
::No, we need to make sure the demo stops at the natural end of a
small but complete story, and that audience members understand our
key points.
#### Does the demo raise questions that it does not answer?
::No, the demo is very complete.
::Yes, but we anticipate those questions and can handle them in the
Q&A period.
::Yes, the goal of this demo is to raise questions and issues that we
will then work to resolve.

196
ProductDocumentation/Design-Architecture.md Normal file
View File

@ -0,0 +1,196 @@
##### Project
::PROJECT-NAME(Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Design](Design) > Design Architecture
- [Software Requirements Specification](SRS)
- [Glossary](Glossary)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
*TODO: Answer the questions below to help you define your system
architecture. Some example text is provided.*
### Overview
#### What are the most important facts that a developer should know about this system architecture?
::PARAGRAPH OR BULLETS
#### What software architecture style is being used?
- ::Single-process desktop application (with plug-in extension modules).
- ::Client-server with a custom thick-clients and server.
- ::2-tier web application: webserver/app-server, database.
- ::3-tier web application: webserver, app-server, database.
- ::Single web service: app-server, database.
- ::Network of web services.
- ::Peer-to-peer with/without central server.
- ::Pipe-and-filter.
- ::Computing grid / distributed servers.
#### What are the ranked goals of this architecture?
1. ::[Ease of integration](Glossary-Standard-Terms#ease_of_integration)
2. ::[Extensibility](Glossary-Standard-Terms#extensibility)
3. ::[Capacity matching](Glossary-Standard-Terms#capacity_matching)
### Components
#### What are the components of this system?
::The components of this system are clearly defined in this [UML Model
with Component Diagram](LINK-TO-MODEL).
::The components of this system are listed below by type:
- ::Presentation/UI Components
- ::[C-00: COMPONENT-NAME](Design-Components#c-00)
- ::Application Logic Components
- ::[C-10: COMPONENT-NAME](Design-Components#c-10)
- ::Data Storage Components
- ::[C-20: COMPONENT-NAME](Design-Components#c-20)
### Deployment
#### How will the components be deployed to processes and machines?
::The deployment of components to processes and machines is clearly
defined in this [UML Model with Deployment Diagram](LINK-TO-MODEL).
::The deployment of components to processes and machines is clearly
defined below:
- ::All-in-one server
- ::Tomcat process
- ::[C-00: Tomcat web server](Design-Components#c-00)
- ::[C-10: PROJECT-NAME
application](Design-Components#c-10)
- ::Database process
- ::[C-20: COMPONENT-NAME](Design-Components#c-30)
::The deployment of components to processes and machines is clearly
defined below:
- ::Load-balanced front-end servers
- ::[C-01: COMPONENT-NAME](Design-Components#c-00)
- ::Back-end server
- ::JVM process
- ::[C-00: COMPONENT-NAME](Design-Components#c-00)
- ::[C-10: COMPONENT-NAME](Design-Components#c-10)
- ::[C-11: PLUG-IN COMPONENT-NAME](Design-Components#c-11)
- ::[C-12: PLUG-IN COMPONENT-NAME](Design-Components#c-12)
- Database process
- ::[C-20: COMPONENT-NAME](Design-Components#c-30)
#### What aspects/resources of their environment are shared?
::Everything is on one server so all machine resources are shared by
all components.
::All machines share the same bandwidth to the Internet. All machines
access the same file server. So, if one component uses the resources
heavily, other components may have to wait.
#### How are requests allocated to redundant or load-balanced servers?
::We are not doing any load-balancing or redundancy for fail-over.
::Load-balancing among front-end servers is handled by a load
balancing device that we can make very few assumptions about.
However, once a user session is established, the same front-end
server will be used for all requests during that session.
#### What alternative deployment configurations are possible?
::This is the only possible deployment.
::The database could be moved to a different machine with a fairly
simple change to a configuration file. Otherwise, nothing can be
changed about the deployment.
::We have the ability to move the database process to a
separate machine. We have the ability to add more front-end servers.
The application logic running on the application server cannot be
split or load-balanced.
### Integration
#### How will components be integrated? Specifically, how will they communicate?
::All of our code uses direct procedure calls. The database is
accessed through a driver.
::Components within the same process use direct procedure call or
standard Java events. Plug-ins are also accessed through a API of
direct procedure calls and standard events. Communication with the
database uses a JDBC driver. Communication between the front end-and
back-end servers uses XML-RPC.
#### What architectural mechanisms are being used to ease future extensions or modifications?
::We could change the database by switching drivers. Otherwise,
extensions and modifications can only be done at the design level.
::New front-end components could be added so long as they access the
back-end the same way. New plug-in components can be dynamically
loaded, so long as they satisfy the plug-in API. Otherwise, there is
no ability to add or exchange components, because this architecture
uses direct dependencies between its components rather than
implicit invocation. Extensions and modifications can be made at the
design-level, but deploying those changes requires recompilation
and down-time.
### Architectural Scenarios
*TODO: Provide architecture scenarios that show how objects will
communicate across components, processes, and machines. Focus on
scenarios where the architecture itself is changing, e.g., system
startup, shutdown, adding or upgrading components, load balancing or
fail-over.*
The following sequence diagrams give step-by-step descriptions of how
components communicate during some important usage scenarios:
- ::[System startup](LINK-TO-DIAGRAM)
- ::[System shutdown](LINK-TO-DIAGRAM)
- ::[SCENARIO NAME](LINK-TO-DIAGRAM)
### Architecture Checklist
*TODO: Evaluate your architecture with respect to each of your goals.*
#### Ease of integration: Have mechanisms been provided for all needed types of integration?
::Yes. In this system, all of the new components are designed to
work together. And, the reused components are integrated via fairly
simple interfaces.
#### Extensibility: What types of components can be added later and how?
::See above.
#### Capacity matching: How has this architecture matched component resource needs to machines?
::The database can be on a machine with RAID disks and a hot-swappable
power supply, while the web front-end components can be on cheaper
machines that could fail individually without causing
system downtime. The front-end web servers and application server
are both CPU-intensive, so they are deployed to different CPUs. The
database is disk-intensive, so it can be deployed to the same
machine as the CPU-intensive application server, with only moderate
competition for resources.
#### Has the architecture been communicated to the development team and other stakeholders?
::Yes, everyone understands. Feedback is welcome.
::No, this is a risk that is noted in the [Risk Management](Project-Plan#Risk-Management) section.

127
ProductDocumentation/Design-Components.md Normal file
View File

@ -0,0 +1,127 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Design](Design) > [Architecture](Design-Architecture) > Design Components
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
*TODO: Briefly describe each component in the system. Focus on
architectural issues such as communication mechanisms, environmental
concerns that affect deployment options, and concurrency. Note key
aspects of each interface, but avoid duplicating details of interfaces
that are specified in the UML class diagrams or other documents.*
Each interface can be an API (application program interface), standard
protocol (e.g., HTTP), config files, input data file format, or
interactive user interface (e.g., command-line or GUI). One component
may have multiple interfaces: e.g., a server may handle requests in a
standard protocol, but also have a config file, command-line options, an
administrative control panel GUI, and a performance monitoring API.
*TIP: Use an HTML anchor for each component so that a direct link can be
made from other documents, issues, and email messages.*
---
### C-00: COMPONENT NAME
**Description:**
::DESCRIPTION
**Environmental Constraints:**
::REQUIRED OPERATING SYSTEM, RAM, ETC.
**Available Interfaces:**
::BRIEFLY DESCRIBE INTERFACES
---
### C-01: COMPONENT NAME
**Description:**
::DESCRIPTION
**Environmental Constraints:**
::REQUIRED OPERATING SYSTEM, RAM, ETC.
**Available Interfaces:**
::BRIEFLY DESCRIBE INTERFACES
---
### C-10: COMPONENT NAME
**Description:**
::DESCRIPTION
**Environmental Constraints:**
::REQUIRED OPERATING SYSTEM, RAM, ETC.
**Available Interfaces:**
::BRIEFLY DESCRIBE INTERFACES
---
### C-11: COMPONENT NAME
**Description:**
::DESCRIPTION
**Environmental Constraints:**
::REQUIRED OPERATING SYSTEM, RAM, ETC.
**Available Interfaces:**
::BRIEFLY DESCRIBE INTERFACES
---
### C-12: COMPONENT NAME
**Description:**
::DESCRIPTION
**Environmental Constraints:**
::REQUIRED OPERATING SYSTEM, RAM, ETC.
**Available Interfaces:**
::BRIEFLY DESCRIBE INTERFACES
---
### C-20: COMPONENT NAME
**Description:**
::DESCRIPTION
**Environmental Constraints:**
::REQUIRED OPERATING SYSTEM, RAM, ETC.
**Available Interfaces:**
::BRIEFLY DESCRIBE INTERFACES

191
ProductDocumentation/Design-Persistence.md Normal file
View File

@ -0,0 +1,191 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Design](Design) > Design Persistence
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
### Overview
*TODO: Answer the questions below to help you design needed persistence
features. Some example text is provided. Add or delete text as needed.*
#### What are the most important facts that a developer should know about persistent data storage in this system?
::PARAGRAPH OR BULLETS
#### What are the ranked goals for persistence in this system?
1. ::[Expressiveness](Glossary-Standard-Terms#dg_expressiveness)
2. ::[Ease of access](Glossary-Standard-Terms#dg_easy_access)
3. ::[Reliability](Glossary-Standard-Terms#dg_data_reliability)
4. ::[Data capacity](Glossary-Standard-Terms#dg_data_capacity)
5. ::[Data security](Glossary-Standard-Terms#dg_data_security)
6. ::[Performance](Glossary-Standard-Terms#dg_data_performance)
7. ::[Interoperability](Glossary-Standard-Terms#dg_data_interop)
### Central Database
#### What is the logical database design?
::The logical database design is described in this [UML
model](LINK-TO-MODEL) or this [ER diagram](LINK-TO-DIAGRAM).
::Additional logical constraints on the database are:
- ::Students can repeat a course (and thus have two records for the
same course in their transcript), if and only if they got a
grade of "C-" or lower, or the course number is 198, 199, 298,
or 299.
- ::A grade of "A+" is valid only for transcript entries during or
after Fall 1990. Prior to that term, the highest possible grade
was an "A".
- ::LOGICAL CONSTRAINT THAT CANNOT BE EXPRESSED IN THE DIAGRAM
- ::LOGICAL CONSTRAINT THAT CANNOT BE EXPRESSED IN THE DIAGRAM
#### What are the physical tables and views?
::The physical database design is described in this [UML
model](LINK-TO-MODEL) or this [ER diagram](LINK-TO-DIAGRAM).
#### How will objects in the application be stored in the database?
::We will use one database table for each class, and one row in the
database for each persistent instance of that class.
::We will use a [library](LINK-TO-LIBRARY) to do our
object-relational mapping. (E.g., torque, castor, JDO,
ADO, hibernate)
#### What database access controls will be used?
::A database user account has been created that has access to the
needed application database tables. The username and password for
this account is stored in a configuration file read by the
application server. The database limits login by that user to only
the IP-address used by the application server.
#### Is this application's central database accessible to other applications?
::Yes. The database is an important point of interoperability for new
applications to be added later. The database itself provides support
for access controls and checks validity constraints so that a
defective application cannot corrupt the database.
::No. This database should always be accessed through
this application. All relevant pieces of information are available
through the application interfaces. The database itself does not
protect against data corruption that could be caused by
other applications.
### File Storage
#### What data needs to be stored in files?
::Nothing is stored in files, everything is in the database.
::The server stores most data in the database, but mailing list
attachments are written to files on the server hard disk.
::All user documents are stored in files on their computer hard disk.
#### What are the conventions for directory structure and file naming?
::N/A
::Files are stored on the server as
```bash
/var/data/attachments/msgNNNN-MMM.dat
```
::Users store files anywhere on their computer, with the filename
extension ```.TST```.
#### What file system access controls will be used?
::N/A
::Files for message attachments are only readable and writable by the
mailing list archiving process that runs as operating system
user "daemon".
::Users can use whatever file permissions they like.
#### What file format will be used?
::The [XYZ](LINK-TO-STANDARD) standard file format.
::A java .properties file.
::A window's .ini file.
::An XML file using [this DTD file](LINK-TO-DTD).
::A simple text file with the following format: ...
::A custom binary file in the following format: ...
### Distributed Storage
#### What information (if any) will be stored on client machines? For how long?
::A cookie will be stored on the user machine for the purpose of
identifying a user session. When the user logs out or closes their
web browser, the cookie is deleted. Most browsers will not even
write this cookie to the disk.
::The a cookie is stored on the user's computer that is equivalent to
their password (but it is NOT actually their password). This cookie
is needed for the auto-login feature. The cookie lasts a maximum of
30 days, and it can only be used from the same IP address.
::User preferences for color scheme are stored in cookies in
their browser. This information is not at all sensitive, so it is
kept indefinitely.
::All the user data will be stored on files on their computers.
### Persistence Mechanisms Checklist
#### Expressiveness: To what extent has this been achieved?
::2-4 SENTENCES
#### Ease of access: To what extent has this been achieved?
::2-4 SENTENCES
#### Reliability: To what extent has this been achieved?
::2-4 SENTENCES
#### Capacity: To what extent has this been achieved?
::2-4 SENTENCES
#### Security: To what extent has this been achieved?
::2-4 SENTENCES
#### Performance: To what extent has this been achieved?
::2-4 SENTENCES
#### Interoperability: To what extent has this been achieved?
::2-4 SENTENCES
#### Has the persistence design been communicated to the development team and other stakeholders?
::Yes, everyone understands. Feedback is welcome.
::No, this is a risk that is noted in the [Risk Management](Project-Plan#Risk-Management)
section.

53
ProductDocumentation/Design-Scalability.md Normal file
View File

@ -0,0 +1,53 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Design](Design) > Scalability
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
### Overview
*TODO: Briefly describe the approach to scalability. Rank your
scalability goals for this design.*
::2-4 SENTENCES.
### Relevant parameters
| Parameter | Description |
|---------------------|-----------------------------------------------------------------------------------------|
| ::registered\_users | ::Number of registered users in the database. |
| ::concurrent\_users | ::Number of users logged into the system at a given time. |
| ::map\_size | ::Number of game squares in the playing area. E.g., a 10 x 25 map would be 250 squares. |
| ::game\_pieces | ::Number of game pieces on the playing area at a given time. |
### Scalability Mechanisms
### Performance Goals and Estimates
| Action | Goal | Time Formula | Description |
|----------------|--------------|-------------------------------|-----------------------------------------------------------------------------|
| ::login | ::1 second | ::O(Log(registered\_users)) | ::Time that it takes to look up a user by their login name in the database. |
| ::display\_map | ::1/5 second | ::O(map\_size + game\_pieces) | ::Time that it takes to redraw the game map and all game pieces. |
### System Scalability Checklist
How well do these mechanisms support the achievement of your goals?
::2-4 SENTENCES
#### Have these scalability mechanisms been communicated to the development team and other stakeholders?
::Yes, everyone understands. Feedback is welcome.
::No, this is a risk that is noted in the
[Risk Management](Project-Plan#Risk-Management) section.

156
ProductDocumentation/Design-Security.md Normal file
View File

@ -0,0 +1,156 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Design](Design) > Design Security
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
### Overview
*TODO: Answer the questions below to help you design needed security
features. Some example text is provided. Add or delete text as needed.*
#### What are the most important facts that a developer should know about the security of this system?
::PARAGRAPH OR BULLETS
#### What are the ranked goals for security in this system?
1. ::[Data security](Glossary-Standard-Terms#data_security)
2. ::[Intrusion prevention](Glossary-Standard-Terms#intrusion_prevention)
3. ::[Abuse prevention](Glossary-Standard-Terms#abuse_prevention)
4. ::[Auditability](Glossary-Standard-Terms#auditability)
### Security Mechanisms
#### What physical security mechanisms will be used?
- ::Servers will be kept in a locked room with door code known only
to administrators.
- ::Servers will be kept in a locked equipment rack.
- ::Server case itself has a security cable that prevents the case
from being opened (so the hard-disk with sensitive data cannot
be removed).
- ::Backup tapes are stored in a locked cabinet in a locked room.
#### What network security mechanisms will be used?
- ::A firewall device limits access to specific network ports (e.g.,
port 80 for web server access).
- ::Firewall software limits access to specific network ports (e.g.,
port 80 for web server access).
- ::Only the front-end machines are accessible over the Internet.
Other machines in the server cluster communicate over a private
LAN only.
- ::Users can only connect to the server from specific ranges of
IP-address (e.g., university-owned computers in networks
on campus).
- ::Certain users (e.g., administrators) can only connect from
specific ranges of IP-addresses.
- ::All network communication takes place over a virtual private
network (VPN) that is encrypted and not accessible to outsiders.
- ::All network communication takes place over a LAN that does not
have any connections to the Internet.
#### What operating system security will be used?
- ::Operating system user accounts will never be created on the
servers, other than those needed by the application itself.
- ::Different components in the application execute as different
operating system users, have only the least possible privileges,
and may only access the particular files needed by
that component.
- ::Operating system permissions on files and directories are set to
prevent undesired access or modification.
- ::Intrusion detection software will be used on the server to
detect any modifications made by hackers.
- ::Administrators will monitor security mailing lists for
announcements of security holes in any components that we use
and security patches and upgrades will be applied quickly.
- ::Data on disks and backup tapes is stored using an encrypted file
system so that the data is protected if the media itself is
stolen or somehow accessed.
#### What application security mechanisms will be used?
- ::Values input into every field are validated before use
- ::Usernames and passwords are required for access
- ::Passwords are stored encrypted
- ::Verification of user email address
- ::The quality of passwords is checked
- ::Users must have certificate files on their client machine before
they can connect to the server
- ::Users must have physical security tokens (e.g., hasp, dongle,
smart-card, or fingerprint reader)
- ::Users are given roles that define their permissions. Those roles
are:
- ::Guest: Visitor to the site is not logged in, no permissions
to change anything
- ::Guest: Visitor to the site is not logged in, can post
messages anonymously
- ::RegisteredUser: User is logged in, has permissions for X, Y,
and Z
- ::Administrator: Permission to change anything, even on behalf
of other regular users
- ::Each action (information display or change) requires that the
user has a role with proper permissions
- ::Compromised or abused accounts can be quickly disabled
by administrators. >
- ::Administrators can review user > permissions
- ::Administrators can audit all a > ccesses and changes
- ::All communications with the us > er are encrypted (e.g., SSL)
- ::Some communications with the user (e.g., the username
and password) are encrypted (e.g., SSL)
- ::Sessions are tied to a particular client IP-address so that
stolen cookies cannot be used.
- ::Session cookies are long random strings that cannot be guessed.
- ::Sessions time out so that unattended terminals cannot be abused.
- ::Actions that seem to destroy data actually move it to a place
where it can still be reviewed by administrators.
- ::Sensitive data, such as credit card numbers, are processed but
not retained in any database or file
- ::The data access layer will be responsible for preventing SQL
injection attacks (i.e., hackers attempting to enter SQL
statements through application UI fields).
- ::The data access layer will allow read-only connections, which
will be used for most requests, as well as write connections for
requests that update the database.
- ::The HTML generation layer will be responsible for preventing
cross-site-scripting (XSS) attacks.
- ::The application will prevent CSRF attacks. It will do this by
performing updates to the database only after a POST, and
checking that the referring page was served by the system for
every POST. Browsers that do not report HTTP-Referrer will not
be supported.
### Security Checklist
#### Protection of data: To what extent has this been achieved?
::2-4 SENTENCES
#### Prevention of intrusion: To what extent has this been achieved?
::2-4 SENTENCES
#### Prevention of abuse: To what extent has this been achieved?
::2-4 SENTENCES
#### Accountability/auditing: To what extent has this been achieved?
::2-4 SENTENCES
#### Have these security mechanisms been communicated to the development team and other stakeholders?
::Yes, everyone understands. Feedback is welcome.
::No, this is a risk that is noted in the [Risk Management](Project-Plan#Risk-Management) section.

126
ProductDocumentation/Design-Src-Org.md Normal file
View File

@ -0,0 +1,126 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Design](Design) > Source Code Organization and Build System
- ::[Example build.xml for Tomcat](http://jakarta.apache.org/tomcat/tomcat-4.1-doc/appdev/build.xml.txt)
- ::[Apache Ant manual](http://ant.apache.org/manual/index)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
### Overview
*TODO: Answer the questions below to help you define your source code
organization and build process. Some example text is provided. Add or
delete text as needed. E.g., not all projects try to be platform
independent.*
#### What are the most important facts that a developer should know about this source code organization and build system?
::It roughly follows the standard proposed in the Tomcat documentation
and is very similar to the organization used on many open source
projects at the Apache Software Foundation.
#### What are the ranked goals of this source code organization and build system?
1. ::Separation of files by type
2. ::Separation of version-controlled files from files generated by
the build process
3. ::Compatibility with standard build processes
4. ::Platform independence
### Key Directories and Files in Developer Working Copies
*TODO: Describe the purpose of each directory that will appear in a
developer's work copy, also include any files that are important to the
overall structure or build process.*
| Path | VC | Description |
|--------------------------------------|-------|---------------------------------------------------------------------------------|
| ::build.xml | ::Yes | ::Build file |
| ::build.properties | ::Yes | ::Build properties file |
| ::src/ | ::Yes | ::Source code |
| ::src/java/ | ::Yes | ::Java source code |
| ::src/java/\[Nested packages\]/ | ::Yes | ::Java source code of classes in each package |
| ::src/java/\[Nested packages\]/test/ | ::Yes | ::Java source code of unit tests for classes in each package |
| ::web/ | ::Yes | ::HTML and JSP files |
| ::web/css/ | ::Yes | ::CSS files, if any |
| ::web/images/ | ::Yes | ::Image files, if any |
| ::web/WEB-INF/web.xml | ::Yes | ::Java web application configuration file |
| ::conf/ | ::Yes | ::Configuration files, if any |
| ::data/ | ::Yes | ::Initial data to load into database and/or file system, if any |
| ::lib/ | ::Yes | ::Libraries reused by this project, if any |
| ::scripts/ | ::Yes | ::Command-line utility scripts used by this project, if any |
| ::www/ | ::Yes | ::Project documents (e.g., overview, plan, requirements, and design) |
| ::build/ | ::No | ::Output of build process |
| ::build/WEB-INF/classes/ | ::No | ::Compiled code output by build process |
| ::dist/docs/api/ | ::No | ::API documentation output from build process |
| ::dist/PROJECT-NAME-VERSION.war | ::No | ::Deployable web archive of classes and config files generated by build process |
### Build Targets
*TODO: Describe the build targets that developers will use in daily
development. The examples below should fit most projects.*
| Target | Description |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ::compile = default | ::Compiles Java source code and creates .class files under the "build" directory. |
| ::dist | ::Packages the system for distribution/deployment to servers or end users. Specifically, it creates .war archive of compiled classes and configuration files. |
| ::install | ::Places executable code into location where it will actually be executed. Specifically, it copies .war file into Tomcat's webapps directory for use. You must then restart Tomcat or use the "reload" link in the Tomcat Manager. |
| ::javadoc | ::Generates Java API documentation under "build/docs/api/". |
| ::clean | ::Deletes files generated by previous build commands. Files under version control are not touched. |
### Build Configuration Options
| Property | Description |
|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ::app.name | ::The name of this application. This should be one short word. Used in the name of resulting package files. Specifically, the .war file. And, it will be used to access the application via http://localhost:8080/APP.NAME/ |
| ::app.version | ::Version number of this release. Used in the name of resulting package files. Specifically, the .war file. |
| ::webapps.path | ::Path to the Tomcat "webapps" directory. Defaults to C:\Program Files\Apache Group\Tomcat 4.1\webapps\ |
::These build system properties can be modified by editing the
build.properties file.
### Source Code Organization and Build System Checklist
#### Separation of files by type: Are files separated by type?
::Yes. Except that application JSP and HTML files are in the same
directory, which is convenient because sometimes we change an HTML
file to be a JSP file.
#### Separation of version-controlled and non-version controlled files: To what extent has this been achieved?
::It has been achieved. Everything is under version control except for
the "build" directory. No step in the build process should create or
modify any file in any other directory.
#### Compatibility with standard build processes: To what extent has this been achieved?
::So far, so good. We can use build.xml files that are very close to
the examples that come with Ant. One difference is that we keep our
technical documentation under "www" rather than under "docs". Also,
we have avoided the use of custom ant tasks.
#### Platform independence: To what extent has this been achieved?
::We are using Ant, which is itself platform independent. The names
of the files and directories should work across platforms because
they do not rely on case-sensitive names. We assume that the utility
scripts in the "scripts" directory support all needed platforms and
we have not created directories for different versions of these files
aimed at specific platforms.
#### Have these implementation decisions been communicated to the development team and other stakeholders?
::Yes, everyone understands. Feedback is welcome.
::No, this is a risk that is noted in the [Risk Management](Project-Plan#Risk-Management) section.

212
ProductDocumentation/Design-UI.md Normal file
View File

@ -0,0 +1,212 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Design](Design) > User Interface
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
### Overview
*TODO: Answer the questions below to help you design the user interface
features of your system. Some example text is provided. Add or delete
text as needed.*
#### What are the most important facts that a developer should know about the user interface of this system?
::PARAGRAPH OR BULLETS
#### What are the ranked goals for the user interface of this system?
1. ::[Understandability and learnability](Glossary-Standard-Terms#understandability_and_learnability)
2. ::[Task support and efficiency](Glossary-Standard-Terms#task_support_and_efficiency)
3. ::[Safety](Glossary-Standard-Terms#safety)
4. ::[Consistency and familiarity](Glossary-Standard-Terms#consistency_and_familiarity)
### Metaphors, Exemplars, and Standards
#### What is the central metaphor of this UI design?
::PARAGRAPH
#### What existing systems have user interfaces similar to the UI you want to build? What specific aspects are similar?
- ::[amazon.com](http://www.amazon.com): Our e-commerce site will
have stores and departments, and search like this site.
- ::[Microsoft Office](http://www.microsoft.com/office/using/default.asp): We
will use configurable toolbars the same way Office 2000 does.
- ::[EXISTING-UI](LINK-TO-SYSTEM): DESCRIPTION
#### What UI design standards, guidelines, and styles are you following?
- ::[Microsoft UI guidelines](http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwue/html/welcome.asp)
- ::[Java UI guidelines](http://java.sun.com/products/jlf/ed1/guidelines.html)
- ::[Mac UI guidelines](http://developer.apple.com/techpubs/macosx/Essentials/AquaHIGuidelines/AHIGHIGs/index.html)
- ::[W3C Accessibility guidelines](http://www.w3.org/TR/WCAG10/)
### Task Models
#### What types of users will use this system?
::See the [user needs document](User-Needs).
#### What types of tasks will those users perform?
::See the [use case suite](Use-Case-Suite).
### Content Model / Interaction Contexts
*TODO: List interaction contexts. Each interaction context is a "place"
where users see information and where they select commands or options.
In a graphical user interface, a interaction context will eventually be
implemented as a window or dialog box. In other applications, an
interaction context may be implemented as, e.g., a web page, a voice
menu prompt, or a physical control panel.*
*TIP: Each interaction context is an exclusive mode: the user can only
use one interaction context at a time. All the components within one
context are visible and usable at the same time. E.g., if a window has
three tabs, that is three interaction contexts because only one tab can
be used at a time.*
*TODO: For each interaction context, list the abstract components within
that context. Each component is a piece of information, or a user
interface affordance. In a GUI, each abstract component will eventually
become a widget, but the choice of specific widgets happens later.
Choice of abstract components corresponds to step 2 in the
[HTML prototyping example](http://www.ics.uci.edu/~jrobbins/htmlproto/index.html)
demonstrated in class.*
*TIP: Most high frequency use cases should be carried out in only one
interaction contexts. A use case that requires three interaction
contexts could be hard to use. However, interaction contexts with too
many components can also be hard to use.*
| Interaction Context --Abstract UI Components | Purpose | Contents / Constraints / Behavior |
|------------------------------------------------|------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ::[Login dialog](LINK-TO-MOCKUP) | ::Verify that the current user is actually the person that they claim to be. | |
| ::--Prompt | ::Tell the user that this dialog is to log in. | ::"Please log in". |
| ::--Message area | ::Give the user some feedback about the login process. | ::Initially blank. Changes to "Checking username and password" when the user presses "Login". Changes to "Invalid username or password, please try again", if login fails. |
| ::--Username | ::Identify the user account that the current user is trying to access. | ::The name of the user account. Regex: [-_a-z0-9]{1-16}. The application should not do anything that would help users guess usernames. E.g., this should not be a combo-box with recent users listed, and it should not offer auto-complete. |
| ::--Password | ::Verify that the current user knows a secret password that only the true user of that user account should know. | ::The password of 4-16 characters. Do not display the password on the screen. The application should not do anything that would help users guess passwords. |
| ::--Login | ::Allow the user to indicate that they have completed entry of their username and password. | ::"Login" Only enabled when Username != "". If the username or password is incorrect, delay a few seconds, and then clear all fields. |
| ::--Lost Password | ::Allow the current user to start a process of generating a new password for a given username. | ::"Forgot your password? Click here." Only enabled when Username != "". |
| ::[PAGE-NAME](LINK-TO-MOCKUP) | ::PURPOSE | |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::[PAGE-NAME](LINK-TO-MOCKUP) | ::PURPOSE | |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::[MAIN-WINDOW-NAME](LINK-TO-MOCKUP) | ::PURPOSE | |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::[DIALOG-NAME](LINK-TO-MOCKUP) | ::PURPOSE | |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::[DIALOG-NAME](LINK-TO-MOCKUP) | ::PURPOSE | |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
| ::--ABSTRACT-COMPONENT-NAME | ::PURPOSE | ::CONTENTS |
### Technical Constraints / Operational Context
#### What are your assumptions about the output devices?
::We assume that the user has a 17-inch or larger screen with 1024x768
pixels that can display thousands of colors (16 bit or more). We
assume basic audio that can play simple sound files.
::We make very few assumptions about the user's screen or web browser,
other than the assumption that they can view page somehow. We will
not use any audio features.
::This "pay-at-the-pump" system has a 320x200 16-color display and
can beep.
#### What are your assumptions about the input devices that you will use?
::We assume only that the user has a standard keyboard and mouse.
::This "pay-at-the-pump" system has digits 0-9, "OK", "Cancel", and
four menu buttons along the right-hand edge of the screen.
#### What are your assumptions about the amount of time users will spend on tasks?
- ::Use cases UC-02 and UC-04 are expected to take a few minutes each.
- ::Use case UC-00 should take less than 5 seconds each. All other use
cases should take less than 30 seconds each.
#### What windowing systems, UI libraries, or other UI technologies will you use?
::Standard Java Swing with no extra libraries.
::Simple HTML and CSS with simple GIF images.
### User Interface Checklist
*TODO: Answer the following questions to help evaluate the design. You
may add or remove questions to fit your project.*
#### Understandability and learnability
##### Are there any labels of icons that are likely to be misunderstood?
::1-3 SENTENCES
##### Is the user's current place and state clearly visible? E.g., wizard step 2 of 5, or edit-mode vs. play-mode.
::1-3 SENTENCES
##### Are advanced options clearly separated from the most commonly used options?
::1-3 SENTENCES
##### Are there no invisible options or commands? E.g., hold down the control key when opening a dialog box to see advanced options.
::1-3 SENTENCES
#### Task Support and Efficiency
##### Which use cases force the user to work through more than two interaction contexts?
::1-3 SENTENCES
##### Which use cases force the user to perform slow or difficult UI steps? E.g., entering a long code number like an ISBN. E.g., long mouse-drag operations.
::1-3 SENTENCES
#### Safety
##### Are there any dangerous or irreversible actions that are done with only one step?
::1-3 SENTENCES
#### Consistency and Familiarity
##### Do UI elements in your system work the same as they do in the existing example systems you identified?
::1-3 SENTENCES
##### Do all elements in your system that appear the same, actually function the same?
::1-3 SENTENCES
##### Are all elements share consistent visual characteristics such as font and color scheme, unless there is a reason for them to differ?
::1-3 SENTENCES
##### Are labels used consistently throughout the system? E.g., not "forward/back" in some contexts and "next/prev" in others.
::1-3 SENTENCES

149
ProductDocumentation/Design.md Normal file
View File

@ -0,0 +1,149 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Attached Worksheets
- Design > [Architecture Worksheet](Design-Architecture)
- Design > [Source Organization and Build Worksheet](Design-Src-Org)
- Design > [Scalability Worksheet](Design-Scalability)
- Design > [User Interface Worksheet](Design-UI)
- Design > [Persistent Storage Worksheet](Design-Persistence)
- Design > [Security Worksheet](Design-Security)
##### Related Documents
- [SRS](SRS) > [Use case suite](Use-Case-Suite)
- [SRS](SRS) > [Feature set](Feature-Set)
- [Glossary](Glossary)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
**Process impact:**
This design document describes a system that will satisfy the requirements of the [SRS](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.
*TODO: Fill in the sections below. Add ore remove items as needed for your project.*
### Introduction
#### How is this design document organized?
This main page describes the system design in terms of packages,
classes, relationships, and behavior. Several attached worksheets
address specific aspects of the overall system design, such as user
interface and database design.
#### What are the most important facts that a developer should know about this design?
::PARAGRAPH or BULLETS
#### What are the prioritized goals of this design?
1. ::[Correctness](Glossary-Standard-Terms#correctness)
2. ::[Feasibility](Glossary-Standard-Terms#feasibility)
3. ::[Understandability](Glossary-Standard-Terms#understandability)
4. ::[Implementation phase guidance](Glossary-Standard-Terms#implementation-and-phase-guidance)
5. ::[Modularity](Glossary-Standard-Terms#modularity)
6. ::[Extensibility](Glossary-Standard-Terms#extensibility)
7. ::[Testability](Glossary-Standard-Terms#testability)
8. ::[Efficiency](Glossary-Standard-Terms#efficiency)
### UML Structural Design
*TODO: Link to a design model and/or design diagrams that describe your
system's structure in detail.*
#### The system's structural design is described in the following UML model
::[MODEL-NAME](LINK-TO-MODEL-FILE).
#### The system's structural design is described in the following UML structural diagrams
- ::[PACKAGE OVERVIEW DIAGRAM](LINK-TO-DIAGRAM)
- ::PACKAGE-NAME
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::PACKAGE-NAME
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::PACKAGE-NAME
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
::ANY ADDITIONAL NOTES OR COMMENTS
### UML Behavioral Design
*TODO: Link to a design model and/or design diagrams that describe your
system's behavior in detail.*
#### The system's behavioral design is described in the following UML model
::[MODEL-NAME](LINK-TO-MODEL-FILE)
#### The system's behavioral design is described in the following UML behavioral diagrams
- State Diagrams
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- Sequence Diagrams
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- Collaboration Diagrams
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
- ::[DIAGRAM-NAME](LINK-TO-DIAGRAM)
::ANY ADDITIONAL NOTES OR COMMENTS
### UML Design Checklist
*TODO: Answer the following questions to help evaluate your design. Add
or remove questions to fit your project. If you cannot answer a question
positively, that may indicate an aspect of the design that should be
revised.*
#### Correctness: How do you know that this design is correct?
::2-4 SENTENCES
#### Feasibility: What indicates that this design can be implemented and tested with the planned amount of time and effort?
::2-4 SENTENCES
#### Understandability: What makes this design understandable?
::2-4 SENTENCES
#### Implementation phase guidance: Does the design suggest reasonable implementation tasks?
::2-4 SENTENCES
#### Modularity: How have concerns been separated and addressed in distinct modules?
::2-4 SENTENCES
#### Extensibility: How can new features can be easily added later?
::2-4 SENTENCES
#### Testability: What makes this system easy to test?
::2-4 SENTENCES
#### Efficiency: Does the system consume an acceptable amount of time, storage space, bandwidth, and other resources?
::2-4 SENTENCES
#### Has the design been communicated to the development team and other stakeholders?
- ::Yes, everyone understands. Feedback is welcome.
- ::No, this is a risk that is noted in the
[Risk Management](Project-Plan#Risk-Management) section.

19
ProductDocumentation/Document-Cross-Ref.md Normal file
View File

@ -0,0 +1,19 @@
*TODO: This template is not done yet. Feel free to contribute your ideas.*
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.
### Artifact Producer / Consumer Matrix
| Read By \ Written By | Everyone | Project Manager | Product Manager | Dev Team | QA Team | Tech Writer | Tech Support | Operations | Sales |
|------------------------|-----------------|-----------------|-----------------|----------|---------|-------------|--------------|------------|-------|
| ::Everyone | [SDM](SDM) | | | | | | | | |
| ::Project Manager | | | | | | | | | |
| ::Dev Team | | | | | | | | | |
| ::QA Team | | | | | | | | | |
| ::Tech Writer | | | | | | | | | |
| ::Tech Support | | | | | | | | | |
| ::Operations | | | | | | | | | |
| ::Sales | | | | | | | | | |

106
ProductDocumentation/FAQ.md Normal file
View File

@ -0,0 +1,106 @@
*TODO: Answer these common questions. Some sample answers are provided
for you. Add new questions and new sections to fit the needs of your
users.*
*TIP: This FAQ is for end users, you may want to write FAQ's for other
types of stakeholders such as potential customers, open source
contributors, members of a developers' network, or administrators.*
### General Information
#### What is ::PRODUCT-NAME?
::It is a XXXXX. Read our [PRODUCT-NAME overview](http://www.COMPANY.com/products/PRODUCT-NAME/).
#### Who should use ::PRODUCT-NAME?
::Anyone who wants XXXXXXX. Read more about our [target audience and benefits](Target-and-Benefits).
### Download and Install
#### How can I obtain ::PRODUCT-NAME?
::You may [download PRODUCT-NAME](LINK-TO-DOWNLOAD).
::You may [place an order for PRODUCT-NAME](LINK-TO-ORDER).
#### What do I need to use ::PRODUCT-NAME?
::System requirements are described in the [release notes](Release-Notes).
::System requirements are a Intel-compatible PC with a processor speed
of at least XXX MHz, XXX MB of RAM. XXX MB of free disk space, and
one of the following operating systems: Windows 98/2000/XP, Mac
OSX, Linux.
#### How do I install ::PRODUCT-NAME?
::[Installation instructions](install.html) are available on-line.
#### How do I upgrade from an older version of PRODUCT-NAME?
::[Installation instructions](install.html) are available on-line.
### Getting Started
#### What is ::TECHNICAL-TERM?
::It means XXXXX. For additional technical terms, see the
[glossary](Glossary).
#### What is ::GUI-ELEMENT?
::It is a XXXXX. It is used for YYYYY.
#### How do I do ::COMMON-TASK?
::You should understand that XXX. Once you are ready, you can:
1. ::Step one
2. ::Step two
3. ::Step three
### SECTION NAME
#### ::QUESTION?
::ANSWER.
#### ::QUESTION?
::ANSWER.
#### ::QUESTION?
::ANSWER.
#### ::QUESTION?
::ANSWER.
### Troubleshooting
#### ::I see an error message "ERROR-MESSAGE". What's wrong?
::ANSWER.
#### ::I can't do COMMON-TASK. What's wrong?
::ANSWER.
### Other Questions
#### ::My question is not on this page. How do I find the answer?
::First read the [user guide](user-guide) and other
on-line help. Your question may have already been asked and
answered, to find it: search the project [mail archives](#) and
[issue tracking system](#). If you still don't find it, you can ask
the question on the [users' mailing list](#) or the [developers'
mailing list](#) or you can [enter an issue](#).
#### ::Where should I send comments on this FAQ?
::You can write to [EMAIL-ADDRESS](mailto:#) or any of the developers
on the [developers' mailing list](mailto:#).

110
ProductDocumentation/Feature-Format.md Normal file
View File

@ -0,0 +1,110 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [SRS](SRS) > [Feature Set](Feature-Set) > Feature Specification Format
---
**Process impact:** This reference page documents the format of feature
descriptions and gives tips on writing them. You can copy and paste the
feature specification template into your [Features](Features)
document. This file itself should not be edited to hold specific
features.
*TODO: Copy and paste this feature specification template as many times
as needed in your [Features](Features) document.*
---
### ::F-00: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risk | 2-Risk | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::NOTE
- ::QUESTION
- ::QUESTION
---
### Feature Attribute Values
- Priority
- Essential: The system could not or would never be used without
this feature. It would be much harder to test, document, or
package the product without this feature.
- Expected: Key stakeholders strongly desire and expect
this feature. It may have been promiDIAGRAMsed to them in a certain
release. It's absence would substantDIAGRAMially reduce the success of
the project.DIAGRAM
- Desired: Stakeholders desire this feDIAGRAMature. It's absence would
reduce the success of the project.
- Optional: This feature would be nice to have. Adding it could
have some advantage, but delaying it would not have a big effect
on the success of the project.
- Effort
- Months: A very large feature that is too big to estimate and
should be broken in to smaller, better-defined features.
- Weeks: A large feature that will take 40 to 160 hours to add.
- Days: An average or easy feature that would take less than 40
hours to add.
- Hours: A very easy feature that would take less than 8 hours to
add
- Note that "adding" a feature means doing all of it's design,
implementation, technical documentation, user documentation,
and testing. Even the easiest feature takes hours to add.
- Risk
- Dangerous: Implementing this feature successfully would require
overcoming risk factors that are more than three or unknown
in number. It should be broken down into parts, better
specified, or risk factors should be eliminated prior
to implementation.
- 3-Risks: Implementing this feature would require three risk
factors to be overcome. Any single release should contain at
most a few such high-risk features, and contingency plans should
be considered. You should be able to list the risks.
- 2-Risks: Implementing this feature would require two risk
factors to be overcome. This is normal for challenging features.
You should be able to list the risks.
- 1-Risk: Implementing this feature as specified would require one
risk factor to be overcome. This is normal for many features.
You should be able to describe the risk.
- Safe: Implementing this feature as specified is just a matter of
time and effort, there is no real risk of failure.
- A "risk factor" is a task or fact that is currently in doubt,
but that must turn out well in order for the feature to be
successfully implemented. See tips on managing risk below.
### Further Information
For more information on advice, see:
- Words of wisdom on [feature sets](http://readyset.tigris.org/words-of-wisdom/feature-set.html).
- Words of wisdom on [feature specifications](http://readyset.tigris.org/words-of-wisdom/features.html).

120
ProductDocumentation/Feature-Set.md Normal file
View File

@ -0,0 +1,120 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [SRS](SRS) > Feature Set
- [Project proposal](Proposal) > [User needs](User-Needs)
- [SRS](SRS) > [Use case suite](Use-Case-Suite)
- [Feature format](Feature-Format)
- ::LINK TO USE CASE DIAGRAM
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
**Process impact:** A feature set is simply a table of contents for the
individual feature descriptions. Much like a test suite, organizing the
feature set by priority, functional area, actor, business object, or
release can help identify missing, extra, or poorly motivated features
early.
*TODO: Before writing individual feature descriptions, list all the
features that you think you will need. Organize them so that missing
features appear as blanks on this page, and extra features will appear
to be extras that don't fit anywhere. See the
[feature format](Feature-Format#further-information) document for more
tips on specifying features and feature sets.*
*TIP: Refer back to the user stories in your [user needs](User-Needs)
document and to the [use case suite](Use-Case-Suite).
Use them for ideas and make sure that you cover all of them.*
### Features by Release and Priority
*TODO: Select subset of features can be implemented for a given release.
When features are listed in priority order, choosing the features to
implement in a release simply becomes a matter of "drawing a line":
features below the line must wait for a later release. Make sure to also
consider estimated effort and risk.*
- ::Release 1.0
- ::Essential
- ::[F-00](Features#f-00_site_configuration) Site configuration
- ::[F-01](Features#f-01_user_regisration) User registration
- ::[F-21](Features#f-21_feature_name) NAME OF FEATURE
- ::[F-31](Features#f-31_feature_name) NAME OF FEATURE
- ::Expected
- ::[F-02](Features#f-02_feature_name) NAME OF FEATURE
- ::[F-03](Features#f-03_feature_name) NAME OF FEATURE
- ::[F-20](Features#f-20_feature_name) NAME OF FEATURE
- ::Release 1.1
- ::Expected
- ::[F-22](Features#f-22_feature_name) NAME OF FEATURE
- ::[F-23](Features#f-23_feature_name) NAME OF FEATURE
- ::[F-33](Features#f-33_feature_name) NAME OF FEATURE
- ::Desired
- ::[F-10](Features#f-10_feature_name) NAME OF FEATURE
- ::[F-11](Features#f-11_feature_name) NAME OF FEATURE
- ::[F-12](Features#f-12_feature_name) NAME OF FEATURE
- ::Later Releases
- ::Optional
- ::[F-30](Features#f-30_feature_name) NAME OF FEATURE
- ::[F-32](Features#f-32_feature_name) NAME OF FEATURE
### Features by Release and Risk
- ::Release 1.0
- ::[F-00](Features#f-00_site_configurtion) Safe : Site configuration
- ::[F-01](Features#f-01_user_registration) Safe : User registration
- ::[F-21](Features#f-21_feature_name) Safe : NAME OF FEATURE
- ::[F-31](Features#f-31_feature_name) 1-Risk : NAME OF FEATURE
- ::[F-02](Features#f-02_feature_name) 1-Risk : NAME OF FEATURE
- ::[F-03](Features#f-03_feature_name) 2-Risks : NAME OF FEATURE
- ::[F-20](Features#f-20_feature_name) 2-Risks : NAME OF FEATURE
- ::Total unique risk factors: 4
- ::Release 1.1
- ::[F-22](Features#f-22_feature_name) Safe : NAME OF FEATURE
- ::[F-23](Features#f-23_feature_name) Safe : NAME OF FEATURE
- ::[F-33](Features#f-33_feature_name) Safe : NAME OF FEATURE
- ::[F-10](Features#f-10_feature_name) 2-Risks : NAME OF FEATURE
- ::[F-11](Features#f-11_feature_name) 2-Risks : NAME OF FEATURE
- ::[F-12](Features#f-12_feature_name) 3-Risks : NAME OF FEATURE
- ::Total unique risk factors: 5
- ::Later Releases
- ::[F-30](Features#f-30_feature_name) Safe : NAME OF FEATURE
- ::[F-32](Features#f-32_feature_name) 2-Risks : NAME OF FEATURE
- ::Total unique risk factors: 2
### Features by Functional Area
- ::FUNCTIONAL AREA ONE
- ::[F-00](Features#f-00_site_configuration) Site configuration
- ::[F-01](Features#f-01_user_registration) User registration
- ::[F-02](Features#f-02_feature_name) NAME OF FEATURE
- ::[F-03](Features#f-03_feature_name) NAME OF FEATURE
- ::FUNCTIONAL AREA TWO
- ::[F-10](Features#f-10_feature_name) NAME OF FEATURE
- ::[F-11](Features#f-11_feature_name) NAME OF FEATURE
- ::[F-12](Features#f-12_feature_name) NAME OF FEATURE
- ::[F-13](Features#f-13_feature_name) NAME OF FEATURE
- ::FUNCTIONAL AREA THREE
- ::[F-20](Features#f-20_feature_name) NAME OF FEATURE
- ::[F-21](Features#f-21_feature_name) NAME OF FEATURE
- ::[F-22](Features#f-22_feature_name) NAME OF FEATURE
- ::[F-23](Features#f-23_feature_name) NAME OF FEATURE
- ::FUNCTIONAL AREA FOUR
- ::N/A: These features are completely automated and internal, users
never interact with them
- ::FUNCTIONAL AREA FIVE
- ::TODO: need to write use cases here
- ::Other functional areas
- ::[F-30](Features#f-30_feature_name) NAME OF FEATURE
- ::[F-31](Features#f-31_feature_name) NAME OF FEATURE
- ::[F-32](Features#f-32_feature_name) NAME OF FEATURE
- ::[F-33](Features#f-33_feature_name) NAME OF FEATURE

492
ProductDocumentation/Features.md Normal file
View File

@ -0,0 +1,492 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [SRS](SRS) > [Feature Set](Feature-Set) > Features
- [Feature format](Feature-Format)
- [Project proposal](Proposal) > [User needs](User-Needs)
- [SRS](SRS) > [Use case suite](Use-Case-Suite)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
**Process impact:** This is a set of detailed feature descriptions.
*TODO: For each feature listed in the [feature set](Feature-Set),
give a detailed description of the feature here. Describe each feature
in enough detail that it could be implemented by any member of the
development team (not only someone who already informally knows what to
do).*
*TIP: Start with a short textual description of each feature. Then, add
more formal information as needed to make each description precise and
unambiguous. E.g.,*
- *Precisely define valid inputs, and error handling*
- *Specify data structures with UML or logical schema*
- *Specify UI aspects of features with tiny mock-ups*
- *Specify key decisions with decision trees or tables*
- *Specify key algorithms with pseudo-code or flow charts*
- *Specify state-based behavior with state machines or tables*
- *Specify sequences of events with scenario diagrams*
---
### ::F-00: Site Configuration
Priority: ::Essential
Effort: ::Days
Risk: ::Safe
Functional area(s): ::Administration
Use case(s): ::[UC-00](Use-Cases#UC-00) [UC-11](Use-Cases#UC-11)
Description:
::The site administrators will be able to configure:
- ::The site appearance by choosing a predefined CSS file
- ::Whether the site makes new clans public or private by default
- ::The email address to be used to send critical error reports
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-01: User registration
Priority: **::Essential**
Effort: ::Days
Risk: ::Safe
Functional area(s): ::Administration
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
:: Visitors can come to the site and register themselves. They must provide the following information:
- ::username
- ::email address (twice to catch typos)
- ::real name
Precise Details:
- ::username must be unique (not equal to any other existing user name)
- ::username must be of the form ~~~[a-zA-Z0-9]{2,16}~~~ and is not case sensitive
- ::email address must be of the form ~~~[-a-zA-Z0-9_.]{2,16}@[-a-zA-Z0-9_.]{6,64}~~~
- ::both entries of the email address must match
- ::email address will be verified by sending the user's initial password there
- ::real name must not be empty
- ::leading and trailing spaces are stripped from all fields
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-02: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
:: 1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-03: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-10: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-11: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-12: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-13: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-20: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-21: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-22: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-23: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-30: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-31: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-32: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION
---
### ::F-33: FEATURE NAME
Priority: ::Essential | Expected | Desired | Optional
Effort: ::Months | Weeks | Days | Hours
Risk: ::Dangerous | 3-Risks | 2-Risks | 1-Risk | Safe
Functional area(s): ::WORD, WORD, WORD
Use case(s): ::[UC-01](Use-Cases#UC-01)
Description:
::1-4 PARAGRAPHS. USE BULLETS OR TABLES TO ORGANIZE INFORMATION. LINK TO WORKSHEETS OR ADDITIONAL INFORMATION.
Precise Details:
- ::LOGICAL CONSTRAINT
- ::LOGICAL CONSTRAINT
Notes and Questions:
- ::NOTE
- ::QUESTION

560
ProductDocumentation/Glossary-Standard-Terms.md Normal file
View File

@ -0,0 +1,560 @@
**Process impact:** 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. Check the
[ReadySET glossary](http://readyset.tigris.org/templates/glossary-std.html) for
updates.
Jump to: [General](#general-terms) | [Computer science & technology](#computer-science-and-technology-terms) | [Process](#process-terms) | [Software development tools](#development-tool-terms) | [Requirements](#requirements-terms) | [Design](#design-terms) | [Design goals terms](#desigD-DIAGRAMn-goals-terms) | [QA terms](#qa-terms) | [QA goals terms](#qa-goals-terms) | [Additional terms](#additional-standard-terms)| [Project terms](Glossary)
### General Terms
##### Chipping away
The process of removing sample text from templates when that text
does not apply to the current project. Often some of the sample text
will be kept or revised to fit the current project. Even if the
sample text does not fit the current project, it provides a reusable
example of how to phrase that type of description. The term
"chipping away" comes from an old joke: when a sculptor is asked how
he carved a marble statue of a horse, he replies "It was easy, I
just started with a big block of marble and chipped away everything
that did not look like a horse."
##### Attached worksheetD-DIAGRAM
The idea is similar to fillD-DIAGRAMing in an IRS form and using worksheets
to calculate subtotals or mD-DIAGRAMake specific decisions. That is to say,
there is a hierarchy to theD-DIAGRAM templates: there are the main templates,
and then worksheets for speD-DIAGRAMcific topics. We have divided the
information into several fiD-DIAGRAMles so that each file is focused on one
topic, and so that each filD-DIAGRAMe can be worked on by one person in a
reasonable amount of time.D-DIAGRAM
D-DIAGRAM
##### Process impactD-DIAGRAM
The process impact box on eD-DIAGRAMach template explains where the current
template fits into the softD-DIAGRAMware development process. It usually
includes a brief comment on who should create the document, and who
would be expected to make use of it. You can change the process
impact box, but you should not need to.
##### Checklist
There are two kinds of checklists:
- Many of the templates have a section with questions that help
you check your work in that template. Often the sample answers
to the questions prompt you to take some corrective action.
- For design and code review meetings, there are links to
guidelines and checklists that help you identify common errors
in those artifacts.
##### Sticky note
The idea is similar to a post-it note attached to a document that
tells you do "sign here" or fill in a certain part. There are two
types of sticky notes:
- *TODO: Instructs you on how to fill in the template. This is the
minimum that you need to do. One of the main goals of ReadySET
is to help your team *quickly* carry out basic software
engineering activities. The TODO sticky notes make that easy by
making the templates more self-explanatory.*
- TIP: Helps you think of better ways to fill in the template. One
of the other main goals of ReadySET is to help your team make
better decisions that can make your whole project more
successful. The TIP sticky notes help with that.
After you have done what the sticky note says, you can delete the
sticky note.
### Computer Science and Technology Terms
##### ::API (Application Programming Interface)
An API is a set of functions that one software component makes
available to other software components. That allows other programs
to "call" this program via direct function calls, or more indirect
communications such as [SOAP](#soap) messages.
##### ::SOAP
SOAP (Simple Object Access Protocol) is the message format used by
standard web services. It entails sending an XML document to a
server in order to invoke an operation on the server-side.
[More information on SOAP](http://directory.google.com/Top/Computers/Programming/Internet/Web_Services/SOAP/?tc=1).
### Process Terms
##### Change Control Board (CCB)
A group of people who review proposed changes toD-DIAGRAM the project
requirements and/or source code to accept or reject changes in each
particular release. Proposed changes are usually rejected if they
introduce too much risk or would trigger additional effort (e.g.,
the need to redo a lot of testing on new code). A CCB is usually
composed of managers and representatives of other stakeholders such
as the QA group and key customers.
##### Feature Complete
A release is called "feature complete" when the development team
agrees that no new features will be added to this release. New
features may still be suggested for later releases. More development
work needs to be done to implement all the features and
repair defects.
##### Code Complete
A release is called "code complete" when the development team agrees
that no entirely new source code will be added to this release.
There may still be source code changes to fix defects. There may
still be changes to documentation and data files, and to the code
for test cases or utilities. New code may be added in a
future release.
##### Internal Release Number
An internal release number is the number that the development team
gives each release. Internal release numbers typically count up
logically, i.e., they do not skip numbers. They may have many parts:
e.g., major, minor, patch-level, build number, RC number.
##### External Release Number
External release numbers are the numbers that users see. Often, they
will be the same as the internal release number. That is especially
true if the product being built is a component intended to be reused
by another engineering group in the same development organization.
External release numbers can be different for products that
face competition. External release number are simpler, and may not
count up logically. E.g., a certain major ISP jumped up to version 8
of their client software because their competition had released
version 8. Later, the competition used version "10 Optimized" rather
than "10.1" or "11".
##### Release Number
The term "release number" by itself refers to an
[external release number](#external_release_number). Users normally are not aware
of the existence of any internal release numbers.
### Development Tool Terms
#### Version Control System
::DEFINITION1
#### Commit Log Message
::DEFINITION1
#### Issue Tracker
::DEFINITION1
#### Unit Testing Automation
::DEFINITION1
#### Automated Build System
::DEFINITION1
#### Style Checker
::DEFINITION1
#### Source Code Formatter (Pretty Printer)
::DEFINITION1
#### System Test Automation
::DEFINITION1
### Requirements Terms
#### Feature specification
A feature specification focuses on one feature of a software product
and completely describes how that feature can be used. It includes a
brief description of the purpose of the feature, the input and
output, and any constraints. Individual bullet items give precise
details on all aspects of the feature. One feature may be used in
many different ways as part of many different use cases.
#### Use case
The main part of a use case is a set of steps that give an example
of how an [actor](#actor) can use the product to succeed at
a goal. These steps are called the "Main success scenario", and they
include both user intentions and system responses. One use case may
show how the actor uses several features to accomplish a goal.
#### Actor
A user or an external system that uses the system being built.
### Design Terms
#### ::TERM2
::DEFINITION2
### Design Goals Terms
#### Correctness
This design correctly matches the given requirements.
#### Feasibility
This design can be implemented and tested with the planned amount of
time and effort.
#### Understandability
Developers can understand this design and correctly implement it.
#### Implementation phase guidance
This design divides the implementation into components or aspects
that can correspond to reasonable implementation tasks.
#### Modularity
Concerns are clearly separated so that the impact of most design
changes would be limited to only one or a few modules.
#### Extensibility
New features or components can be easily added later.
#### Testability
It is easy to test components of this design independently, and
information is available to help diagnose defects.
#### Efficiency
The design enables the system to perform functions with an
acceptable amount of time, storage space, bandwidth, and
other resources.
#### Ease of integration
The components will work together.
#### Capacity matching
The architecture deploys components onto machines that provide
needed resources with reasonable total expense.
#### Expressiveness
It allows for storage of all valid values and relationships
#### Ease of access
Application code to access stored data is simple
#### Reliability
Stored data cannot easily be corrupted by defective code, concurrent
access, or unexpected process termination
#### Data capacity
The system can store the amount of data needed.
#### Data security
Protection of sensitive user and corporate data from unauthorized
access or modification
#### Performance
Data can be accessed quickly
#### Interoperability
The database or data files can be accessed and updated by other
applications
#### Intrusion prevention
Prevent, e.g., hackers opening a command shell on our server.
#### Abuse prevention
Prevention of abuse (e.g., using our system to send spam).
#### Auditability
All changes can be accounted for later.
#### Understandability and learnability
Users can reasonably be expected to understand the UI at
first sight. Users will be able to discover additional features
without aid from other users or documentation, and they will be able
to recall what they have learned.
#### Task support and efficiency
The UI is well matched to the users' tasks and it can be used with a
reasonable number of clicks and keystrokes.
#### Safety
Users are not likely to accidentally produce an undesired result
(e.g., delete data, or send a half-finished email).
#### Consistency and familiarity
Users can apply their knowledge of similar UIs or UI standards to
this system.
### QA Terms
#### Bug
*n.* **Deprecated** since 1991. See [defect](#defect).
#### Error
*v.* A mistaken thought in the developer's mind. Often caused by
miscommunication or bad assumptions. Errors can create
[defects](#defect). E.g., a developer might erroneously think that
the square root of -4 is -2.
#### Defect
*n.* The result of the developer's [error](#error) embodied in the
product source code, initial data, or documents. E.g., a square root
function which allows negative numbers as arguments is defective.
Defects can be removed by changing the source code, initial data,
or document.
#### Fault
*n.* The execution of defective code. E.g., if a certain input is
provided to defective code, it may cause an exception, or go into an
infinite loop, or store an incorrect value in an internal variable.
A fault is not normally visible to users, only the
[failure](#failure) is visible.
#### Failure
*n.* The user-visible result of a [fault](#fault). E.g., an error
message or an incorrect result. This is evidence that can be
reported in a defect report. Developers use failure evidence during
debugging to eventually find and remove [defects](#defect).
### QA Goals Terms
#### Functionality > Correctness
Correctness is the most basic quality goal. It means that, when
valid inputs are given and the system is in a valid state and under
reasonable load, the system's behavior and results will be correct.
#### Functionality > Robustness
Robustness is the system's ability to gracefully handle
invalid inputs. It should never be possible for any user input to
crash the system or corrupt data, even if that user input is
abnormal, unexpected, or malicious.
#### Functionality > Accuracy
Accuracy refers to the mathematical precision of calculations done
by the system. Any system that does numeric calculations must
consider accuracy, e.g., financial or scientific applications.
#### Functionality > Compatibility
Systems that claim to follow standards or claim compatibility with
existing systems must adhere to the relevant file formats,
protocols, and APIs. The relevant standards are linked at the top of
this document.
#### Functionality > Factual correctness
Is the data in the system a true representation of the real world?
Any system that contains initial data or gathers data about the real
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
#### Usability > Understandability and Readability
Users need to understand the system to use it. The basic metaphor
should be understandable and appropriate to user tasks. Some defects
in understandability include unclear metaphors, poor or hard-to-see
labels, lack of feedback to confirm the effects of user actions, and
missing or inadequate on-line help.
#### Usability > Learnability and Memorability
Every user interface contains some details that users will need to
learn and remember. E.g., Alt-F to open the "File" menu. UI cues and
rules can make these details easier to learn and remember. E.g., the
"F" is underlined and, as a rule, the first letter is usually the
accelerator key.
#### Usability > Task support
This is the quality of match between user tasks and the system's UI.
Task support defects are cases where the system forces the user to
take unnatural steps to accomplish a task or where the user is given
no support for a difficult step in a task. E.g., must the user
invent an 8-character filename for their "Christmas card list"?
E.g., must users total their own tax deductions?
#### Usability > Efficiency
Users should be able to accomplish common tasks with
reasonable effort. Common tasks should be possible with only one or
two steps. The difficulty of each step should also be considered.
E.g., does the user have to remember a long code number or click on
a very small button?
#### Usability > Safety
Humans are error-prone, but the negative effects of common errors
should be limited. E.g., users should realize that a given command
will delete data, and be asked to confirm their intent or have the
option to undo.
#### Usability > Consistency and Familiarity
Users should be able to apply their past experience from other
similar systems. This means that user interface standards should be
followed, and common conventions should be used whenever possible.
Also, UI elements that appear in several parts of the UI should be
used consistently, unless another UI quality takes priority. E.g.,
if most currency entry fields do not require a dollar-sign, then one
that does demand it is a consistency defect, unless there is a real
chance that the user is dealing with anoD-DIAGRAM
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
in his/her task.
#### Usability > Subjective satisfactionD-DIAGRAM
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
Users should feel generally satisfied with the UI. This is a
subjective quality that sums up the other user interface qualities
as well as aesthetics.
#### Security
The system should allow usage only by authorized users, and restrict
usage based on permissions. The system should not allow users to
side-step security rule or exploit security holes. E.g., all user
input should be validated and any malicious input should
be rejected.
#### Reliability > Consistency under load
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
#### Reliability > Consistency under concurrency
Systems that allow concurrent access by multiple users, or that use
concurrency internally, should be free of race conditions
and deadlock.
#### Reliability > Availability under load
Every system has some capacity limits. What happens when those
limits are exceeded? The system should continue to service those
requests that it is capable of handling. It should not crash or sD-DIAGRAM
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
processing all requests.
#### Reliability > Longevity
The system should continue to operate as long as it is needed. ItD-DIAGRAM
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
should not gradually use up a limited resource. Example longevityD-DIAGRAM
D-DIAGRAM
D-DIAGRAM
D-DIAGRAM
defects include memory leaks or filling the disk with log files.
#### Efficiency
The system's operations should execute quickly, with reasonable use
of machine and network resources. E.g., if one user does one
operation, it should execute efficiently.
#### Scalability
Scalability is a general quality that holds when the system
continues to satisfy its requirements when various usage parameters
are increased. E.g., a file server might be scalable to a high
number of users, or to very large files or very high capacity disks.
Several specific scalability goals are listed below.
#### Scalability > Performance under load
This is a specific type of scalability goal dealing with the
performance of the system at times when it is servicing many
requests from many users.
#### Scalability > Large data volume
This is a specific type of scalability goal dealing with the ability
for the system to handle large data sets. Operations should continue
to be correct and efficient as data set size increases. Furthermore,
the user interface should still be usable as the data presented to
users increases in length.
#### Operability
The long-term needs of system administrators should be
reliably supported. E.g., is the system easy to install? Can the
administrator recover from a crash? Is there sufficient log output
to diagnose problems in the field? Can the system's data be backed
up without downtime? Can the system be upgraded practically?
#### Maintainability > Understandability
Will it be easy for (future) developers to understand how the system
works?
#### Maintainability > Evolvability
Can the system easily be modified and extended over time?
#### Maintainability > Testability
Can the system easily be tested? Do the requirements precisely
specify possible inputs and the desired results? Can the system be
tested in parts? When failures are observed, can they be traced back
to defects in specific components (i.e., debugging)? Is testing
practical with the available testing tools?
### Additional Standard Terms
For additional standard terms, see the following reference sites:
- [Dictionary.com](http://www.dictionary.com/)
- [Whatis.com](http://www.whatis.com/)
- [NIST Dictionary of Algorithms and Data Structures](http://www.nist.gov/dads/)
- [Free on-line dictionary of computing](http:/http://foldoc.doc.ic.ac.uk/foldoc/index.html)
- [IBM's glossary of computing terms](http://www-3.ibm.com/ibm/terminology/goc/gocmain.htm)
- [Jargon File](http://www.jargon.org/)

113
ProductDocumentation/Glossary.md Normal file
View File

@ -0,0 +1,113 @@
**Process impact:** This file as a dictionary of terms defined as they
are used during the 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.
Jump to: [A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [F](#f) |
[G](#g) | [H](#g) | [I](#i) | [J](#j) | [K](#k) | [L](#l) | [M](#m) |
[N](#n) | [O](#o) | [P](#p) | [Q](#q) | [R](#r) | [S](#s) | [T](#t) |
[U](#u) | [V](#v) | [W](#w) | [X](#x) | [Y](#y) | [Z](#z) |
[Standard terms](glossary-std.html#standard_terms)
### Project-specific Terms
*TIPs:*
- *Define HTML anchors on your terms with id="TERMNAME" so that other
documents can link to the definition of specific terms.*
- *If there is any question about the meaning of a term, note it here.
If someone (e.g., the customer) gave you a definition to use, note
that here too. If something is best defined by using a hyperlink to
another document or website, include a hyperlink in the definition.*
- *If a term was used in the past, but is no longer going to be used,
you should keep it in the list, mark it as "deprecated", and link to
the term or terms that replace it. E.g., deprecated standard term
[bug](glossary-std.html#bug).*
- *Define only project-specific terms, or ones that a new team member
would not know. Don't define standard textbook terms that can be
easily found elsewhere.*
- *This glossary can serve as simple domain model or data dictionary.
You can define important data objects by describing their meaning
and key attributes. For example, see [student](#student) and
[GPA](#gpa).*
#### A
#### B
#### C
##### ::Class standing
- ::Computed attribute of [student](#student) based on number of
academic units completed. Used to determine priority in
course enrollment.
- ::Real-world meaning of values:
| | |
|-------------|---------------------------------|
| ::Freshman | ::Less than 90 units |
| ::Sophomore | ::Between 90 and 180 units |
| ::Junior | ::Between 180 and 270 units |
| ::Senior | ::More than 270 units completed |
#### D
#### G
##### ::GEF
::*n.* The [Graph Editing Framework](http://gef.tigris.org/). An open
source library for editing diagrams (boxes and arrows).
##### ::GPA
::*n.* Grade Point Average. GPA is a float between 0.00 and 4.00,
accurate to 2 decimal places. Computed from average of completed
course grades in transcript weighted by course units. Used to
determine student ranking, and to trigger Dean's List and
academic probation.
#### I
##### ::ICS
::*n.* Acronym for the [School of Information and Computer
Science](http://www.ics.uci.edu/) at [UC Irvine](http://www.uci.edu/).
#### S
##### ::Student
::*n.* A person who attends a school to earn a degree. Persistent
attributes include: student\_id\_number (primary key), GPA, major,
and years\_at\_school.
##### ::Senior
::*n.* A senior is special type of [undergraduate](#undergraduate) who
has a certain number of course credits on his or her transcript.
Years\_at\_school does not determine senior standing. TODO: how many
credits needed?
#### T
##### ::Term1D-DIAGRAM
::Definition1
##### ::Term2
- ::Definition2a
- ::Definition2b
##### ::Term3
::Definition3
#### U
##### ::Undergraduate
::A type of [student](#student). *TODO: add more detail.*

57
ProductDocumentation/Home.md Normal file
View File

@ -0,0 +1,57 @@
### Mission and Scope
*TODO: Answer these questions in your own words by filling in each*
#### What problem does this project address?
::2-4 SENTENCE PROBLEM
#### What is the goal of this project?
::2-4 SENTENCE GOAL
#### What is the scope of this project?
::2-4 SENTENCE SCOPE
#### What development methodology is being used?
::See our [software development methodology](sdm) document.
#### Where should a new team member start?
::For more information, see the [project proposal](Proposal).
### Status
*TODO: Briefly describe the status of this project. E.g., what phase are
you in? And, what is your next major milestone? Detailed project status
is written in the status reports, not here.*
::We have completed our second beta release and are currently working on
adding more of the functionality described in our product
[specification](srs) and fixing defects.
::The next major milestone is a third beta release with nearly complete
functionality and a wider set of testers.
### Project Documents
|By Activity |Documents |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Inception: | [Home](Home), [Project Proposal](Proposal), [Target Audience and Benefits](Target-and-Benefits), [Statement of User Needs](User-Needs) |
| Reference: | [Glossary](Glossary), [Software Development Methodology](SDM), [Document Cross Reference](Document-Cross-Ref), [All-in-one project summary](Summary) |
| Elaboration: | [Project Plan](Project-Plan), [Software Requirements Specification](SRS), [Feature Set](Feature-Set), [Use Case Suite](Use-Case-Suite), [Design](Design), [QA Plan](QA-Plan), [Test Suite](Test-Suite) |
| Construction: | [Review Meeting Notes](Review-Meeting-Notes), [Implementation Notes](Implementation-Notes), [User Guide](User-Guide), [FAQ / Troubleshooting Guide](FAQ) |
| Transition: | [Install / Quick Start](Installation-Guide), [Demo Script](Demo-Script), [Release notes](Release-Notes), [Release checklist](Release-Checklist), [Post Mortem](Post-Mortem) |
| Continuous: | [Status Report](Status-Report) |
|By Audience |Documents |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| For Everyone: | [Home](Home), [Project Proposal](Proposal), [Target Audience and Benefits](Target-and-Benefits), [Statement of User Needs](User-Needs), [Software Requirements Specification](SRS), [Project Plan](Project-plan), [Release Checklist](Release-Checklist), [Glossary](Glossary)|
| For Management: | [Project Resource Needs](Resource-Needs), [Status Report](Status-Report) |
| For Developers: | [Design](Design), [Review Meeting Notes](Review-Meeting-Notes), [Software Development Methodology](SDM) |
| For QA: | [QA Plan](QA-Plan) |
| For End Users: | [Install / Quick start](Installation-Guide), [User Guide](User-Guide), [Release Notes](Release-Notes) |
| For Support and Ops:| [Implementation Notes](Implementation-Notes), [FAQ / Troubleshooting Guide](FAQ) |
| For Sales/Legal: | [Demo Script](Demo-Script), [Legal Issues](Legal) |

215
ProductDocumentation/Implementation-Notes.md Normal file
View File

@ -0,0 +1,215 @@
##### Project
::[PROJECT-NAME](Home)
##### Release(s):
::X.Y.Z
##### Related Documents
- [Software Requirements Specification](SRS)
- [Release notes](Release-Notes)
- [FAQ](FAQ)
- [Glossary](Glossary)
---
**Process impact:** 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 they need to
understand, manage, or begin to troubleshoot the system (i.e., recognize
certain behavior as normal or abnormal). If significantly more
information is needed, it should be organized into a larger "operations
guide".
### Type of Implementation
*TODO: Fill in information that will help other engineers understand this
system at-a-glance. Feel free to use relevant technical terms and name
specific technology platforms.*
#### Type of system
- ::Desktop GUI application ||
- ::Unix-style command ||
- ::Server-side web application ||
- ::Web service ||
- ::Client-side applet ||
- ::Embedded application ||
- ::Reusable library ||
- ::Reusable class framework ||
- ::Browser Plug-in
#### Programming Language(s)
- ::Java ||
- ::Perl, Unix shell scripts
#### Data Storage
- ::Flat files using XML ||
- ::Flat files using Java properties file format ||
- ::Flat files using Java object serialization format ||
- ::SQL database: MySQL
#### UI Technologies
- ::Java Swing ||
- ::XHTML, CSS, JavaScript
##### Security Technologies
- ::Authentication: None needed ||
- ::Authentication: Local username and password file ||
- ::Authentication: LDAP ||
- ::Authorization: Operating system file ownership and read-write-execute flags ||
- ::Authorization: Access control lists ||
- ::Encryption: None needed ||
- ::Encryption: SSL
### Runtime Environment
*TODO: List and describe runtime objects that make up a running system.
These objects may be referred to by name in the sections below.*
#### Processes
- ::Main application process
- ::Client and server processes
- ::Cron tasks
- ::Operating system services or drivers
#### Configuration Files
- ::PRODUCT-NAME.conf: stores application configuration in Java properties file format.
- ::Section of httpd.conf: configures components of the Apache webserver
#### Database Table
- ::TABLE_ONE: Each row represents a ...
- ::TABLE_TWO: Each row represents a ...
- ::TABLE_THREE: Each row represents a ...
- ::See the persistence design document.
#### Data Files
- ::*.ext: Data files saved by the user on their local hard disk.
- ::/var/PRODUCT-NAME/upload-XXXX.dat: Files uploaded to the server.
#### Temporary Files
- ::/tmp/PRODUCT-NAME.pid: Process ID of the currently running server process.
- ::/tmp/upload-XXXX.dat: Files uploaded to the server before they are processed.
#### Log Files
- ::error.log: Serious errors are put in the normal Apache error log. Must be writable by Unix user httpd.
- ::PRODUCT-NAME.log: Messages indicating the progress of normal operations and some errors. Must be writable by Unix user httpd.
- ::Log files are rotated nightly. Old logs are archived in ANOTHER LOCATION.
### Implementation of Specific Features
*TODO: Write short descriptions of interesting or unexpected algorithms,
limiting assumptions, or any other implementation detail that will
impact the work of other groups. E.g., long-running operations that must
not be interrupted. E.g., start up or shutdown scripts that are
automatically run by the operating system.*
- ::Feature name: 1-3 SENTENCE DESCRIPTION
- ::Feature name: 1-3 SENTENCE DESCRIPTION
- ::Feature name: 1-3 SENTENCE DESCRIPTION
- ::DETAILS
- ::DETAILS
- ::DETAILS
- ::Feature name: 1-3 SENTENCE DESCRIPTION
- ::DETAILS
- ::DETAILS
- ::DETAILS
### Operational Procedures
*TODO: Briefly describe procedures that should be followed by operations
engineers when the system is being run in an ASP production environment.*
#### Install
::See the [installation guide](Installation-Guide)
#### Upgrade
::See the [installation guide](Installation-Guide)
#### Start Server
1. ::STEP 1
2. ::STEP 2
3. ::STEP 3
#### Stop Server
1. ::STEP 1
2. ::STEP 2
3. ::STEP 3D-DIAGRAM
#### Reload Config Files
1. ::STEP 1
2. ::STEP 2
3. ::STEP 3
#### Monitor Activity
::Watch the PRODUCT-NAME.log and error.log.
#### Periodic Cleanup
::On rare occasion, /tmp/upload-XXXX.dat files can be left behind. Any such files that are more than a day old can safely be removed.
### Security
*TODO: Write notes on security to help operations engineers keep the
system secure while it is in operation.*
We take the following precautions to make the system secure
- ::STEP
- ::STEP
- ::STEP
The security of the system depends on the following external factors
- ::STEP
- ::STEP
- ::STEP
### Performance and Scalability
*TODO: Write notes on performance and scalability to help operations
engineers operate the system efficiently.*
::NOTES ON PERFORMANCE.
::NOTES ON SCALABILITY.
### Implementation Notes Checklist
Do these implementation notes provide enough information for operations engineers?
- ::Yes, these notes have been reviewed by the operations team and
requested changes have been incorporated.
- ::No, these notes only summarize parts of a larger
[operations manual](LINK-TO-OPERTIONS-MANUAL).
- ::No, a member of the development team is available on-call whenever
the operations team may need help. This is listed in the
[Resource Needs](Resource-Needs) document and in the
[on-call schedule](LINK-TO-ON-CALL-SCHEDULE).
Have these implementation notes been communicated to the operations and development teams and other stakeholders?
- ::Yes, everyone has had a chance to review them. Feedback is welcome.
- ::Yes, it has been posted to the project website.
- ::No, some developers or operations engineers are not aware of
this document. This is a risk that is noted in the
[Risk Management](Project-Plan#risk-management) section of the
[Project Plan](Project-Plan).

95
ProductDocumentation/Installation-Guide.md Normal file
View File

@ -0,0 +1,95 @@
*TODO: Fill in information about this product. Make sure to use the
**product** name and **external** release number, not internal
information.*
##### Product:
::PRODUCT-NAME
##### Release Number:
::X.Y.Z
##### Release Date:
::YEAR/MONTH/DAY
##### Customer Support:
:: For more information or support, please visit our
[website](http://www.COMPANY.com/products/PRODUCT-NAME/) or
email us at <support@COMPANY.com>
---
### Introduction
::This document describes how to install and get started with
PRODUCT-NAME.
### Minimal System Requirements
::System requirements are described in the [release notes](Release-Notes).
### Installation
*TODO: Give detailed installation instructions. Make sure to test these
instructions by doing them yourself on a target machine.*
*TIP: For development releases, or products that are reusable components
rather than end-user applications, you should include information on
needed development and bugging tools, e.g., Ant and JUnit.*
#### What other software must be installed first?
::Before you can install this product, you must install the following
packages:
- ::[Java SDK](http://java.sun.com/)
- ::[Apache Tomcat](http://jakarta.apache.org/)
- ::[MySQL database](http://mysql.com/)
- ::[OTHER PACKAGES](http://)
#### How do I install PRODUCT-NAME?
:: Please follow these steps
1. ::STEP
2. ::STEP
- ::SUB-STEP
3. ::STEP
4. ::STEP
#### How can I uninstall PRODUCT-NAME?
1. ::STEP
2. ::STEP
- ::SUB-STEP
3. ::STEP
4. ::STEP
#### What if I encounter problems?
::Please see the troubleshooting section in the [FAQ](FAQ).
### Getting Started
*TODO: Briefly describe how the user would accomplish one or two of the
main use cases for new users. For development releases or reusable
components, include instructions on running unit tests.*
#### How can I run post-install unit tests?
1. :Compile the source code by typing "ant"
2. :Run unit tests by typing "ant test"
- ::A brief report will be shown on the console
- ::A detailed test report for any failed tests will be
in build/test-out.
#### ::How can I quickly get started using PRODUCT-NAME?
1. ::STEP
2. ::STEP
- ::SUB-STEP
3. ::STEP
4. ::STEP

103
ProductDocumentation/Interview-Checklist.md Normal file
View File

@ -0,0 +1,103 @@
##### Related Documents
- [User Needs](User-Needs)
- [Interview Notes](interview-notes.html)
---
**Process impact:** This checklist will help you plan customer
interviews.
### Pre-Interview Checklist
1. Decide what goals you want to accomplish
2. Prepare a list of questions
- Ask about things you know you need to find out, based on your
current understanding of the requirements
- Keep questions simple. Don't use multi-part questions, break
complex topics into individual questions.
- Confirm key assumptions. E.g., "You are the one who actually
would use this software, right?" "The total needs to be
displayed and updated as each item is scanned, right?"
- Avoid leading or multiple-choice questions because the right
answer might be one that you don't know about yet. E.g., WRONG:
"Would you log in to the system from your desk here or from
home?" RIGHT: "Where are some of the places you would be sitting
when you log in?" "Here in my office, but also when I work with
others sometimes I log in from their office or from a machine in
the lab or conference room... so, I don't want a cookie saved
there."
- Try to find out the priority of each requirement: essential,
expected, desired, or optional.
- Write some more open-ended questions to see if new important
requirements come up.
- Don't ask too many questions that seem out of scope, you could
accidentally change the scope or set incorrect expectations.
E.g., "Would you like the system to also do ten other cool
things?" "Sure!"
3. Select interviewees that represent all important stakeholders
4. Review your questions. Do you think they can be answered? Will they
help achieve your goals? If not, go back and revise.
5. Decide whether you want to do this interview via email, telephone,
or in person
6. Schedule an interview a time and place for the
interviewee's convenience. Plan on the interview lasting one hour.
### Interview Checklist
1. Be prompt, courteous, and business-like
2. Introduce yourself and explain why you are there
3. Make sure that you are interviewing the person you think you are.
Get their contact information (e.g., email address) if you don't
already have it.
4. Ask permission to take notes. Don't record or video tape.
5. Confirm the amount of time you and the interviewee have for
this session.
6. Give a quick indication of the type and number of questions that you
have
7. Work through the questions.
8. Listen. That is why you are there.
9. If the interviewee refers to existing documents, systems, equipment,
or people, make sure that you understand what he or she is
talking about. If it is important, ask if you may have a copy or
screenshot (but, don't ask for anything containing proprietary
information), or make a note of the important aspects of the items
referred to. Note the URLs of any existing public
websites discussed.
10. Try not to answer the questions yourself, or to react to interviewee
requests by making promises to solve problems. Interviews are for
understanding the problems, not solving them or setting schedules
or deliverables.
11. Write down action items to follow up on finding more information.
E.g., if the interviewee starts explaining at length something that
you know you can learn on your own, or if they don't know the answer
and start speculating at length, you should try to move on the
next question.
12. If you find that you have prepared the wrong questions, focus on
getting information that will help you prepare the right
follow-up questions.
13. Finish on time. If you need more time, continue via email or
another meeting.
14. Summarize action items that you will follow up on
15. Ask if the interviewee has any questions for you, or if there was
something more that they wanted you to ask.
16. Make sure to leave contact information
17. Thank the interviewee for their time
### Post-Interview Checklist
1. Within 24 hours, read your notes and fill in any important details
that were said but not written down
2. Type up your notes so that they can be shared with the team and
archived
3. Formulate any important follow-up questions
4. Within 2-3 days, send a follow-up email message to
- Thank the interviewee again
- Confirm that you have their correct email address, and make it
easier for them to reply to you
- Ask any important follow-up questions
- Give status on your action items, if any. E.g., "I searched
Google for that product you mentioned and I couldn't find a
users manual, but I did find a magazine review of it." Or,
"After I interviewed you, I spoke with Bob, and he confirmed
that some current products do cost $0.00."

98
ProductDocumentation/Interview-Notes.md Normal file
View File

@ -0,0 +1,98 @@
##### Project
::[PROJECT-NAME](Home)
##### Interviewer(s)
::PERSON-NAME
##### Interviewee(s)
::PERSON-NAME
##### Date of Interview
::DATE
##### Interview Location
::LOCATION
##### Related Documents
- [Project proposal](Proposal) > [Target audience and benefits](Target-and-Benefits)
- [Interview checklist](Interview-Checklist)
- [Glossary](Glossary)
---
*TODO: Copy this file once for each interview. Fill in the details. Link
to this file from the "Notes from Interviews and Brainstorming" section
of user-needs.md.*
**Process impact:** 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](User-Needs) are referred to when the
[software requirements specification](SRS) is written or updated.
### Interview Questions and Answers
*TODO: Before the interview, plan the questions you will ask. Afterwords,
type up the answers you received and any additional questions and
answers, and any new follow-up questions.*
#### ::How did you learn about the need for this product?
::ANSWER
#### ::What types of users are likely to use this product?
::ANSWER
#### ::Can you give an example of how a user might actually use the product?
::ANSWER
#### ::Is there any risk or downside to using the product?
::ANSWER
#### ::QUESTION1
::ANSWER1
#### ::QUESTION2
::ANSWER2
#### ::QUESTION3
::ANSWER3
#### QUESTION4
::ANSWER4
### New Questions and Action Items
*TODO: Often early interviews will raise more questions than they answer.
Note these new questions and what you must do to find the answer.*
- ::Can we do X?
- ::Do we support Y?
- ::Action item: research topic Z
- ::Action item: Send follow-up email as per [post-interview checklist](Interview-Checklist#post-interview-checklist)
- ::Action item: prepare for next interview with PERSON(S) on DATE
### Other Interview Notes
*TODO: Note anything else that came out of the interview, either
explicitly or implicitly. Remember to confirm things that you picked up
implicitly if there is any doubt. E.g., make a note if the interviewee
uses an unusual meaning for a certain term. Add links to any documents
provided to you by the interviewee.*
- ::NOTE
- ::NOTE
- ::NOTE

126
ProductDocumentation/Legal.md Normal file
View File

@ -0,0 +1,126 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Release Audience:
- ::General availability release ||
- ::Customer-specific release: CUSTOMER(S) ||
- ::Developer release (Internal usage only) ||
- ::Early access release (Controlled external access)
##### Intended Product License:
::Commercial license
##### Related Documents
- [Project proposal](Proposal) > [Target audience and benefits](Target-and-Benefits)
- [Project Plan](Project-Plan) > [Resource needs](Resource-Needs)
- [Glossary](Glossary)
---
**Process impact:** This document outlines legal issues that may affect
this release. Failure to carefully consider these issues may put the
development organization at risk for legal action.
*TODO: Fill in the information above and below. Add or remove rows as
needed. Use the worksheet to help identify legal issues. Seek
professional counsel for review as needed.*
### Ownership of Intellectual Property
| Component | Owner | License | Status | Comments |
|----------------------------|--------------|----------------------|-----------------------------------------------|----------------------------------------------------------------|
| ::Product name | ::Us | ::Trademark | ::Registration pending | ::We must use "(TM)", not "(R)" |
| ::Database | ::VENDOR | ::Commercial license | ::In compliance, paid normal fee | ::Limits us to 2 CPUs/server |
| ::Encryption library | ::VENDOR | ::Commercial license | ::In compliance, signed partnership agreement | |
| ::Clip-art graphics | ::None | ::Public Domain | ::In compliance | |
| ::Sound driver library | ::OS Project | ::BSD | ::In compliance | |
| ::Search engine indexer | ::OS Project | ::GPL | ::In compliance | ::Indexer runs in separate process, does not make our code GPL |
| ::Other library | ::OS Project | ::BSD | ::In compliance | |
| ::Other data | ::Us | ::Copyrighted | ::In compliance | |
| ::Special algorithm patent | ::Us | ::Patent pending | ::In compliance | ::Patent search done, patent application submitted |
### Regulatory Compliance
| Type | Regulation | Status | Comments |
|--------------------------|---------------------------------------------------|-----------------|-----------------------------------------------------------|
| ::Export | ::Strong encryption exports must be declared | ::In compliance | ::We will not distribute out of country |
| ::Privacy | ::Cannot collect personal information from minors | ::In compliance | ::We ask for user age before asking for other information |
| ::Industry certification | ::Game industry rating | ::In compliance | ::We follow guidelines for "Everyone" rating |
> **Possible Status Values**
>
> - In compliance: we are OK to go ahead with this release
> - Waived: we decided not to consider this aspect for this release
> - Violated: we are not conforming. Comment should describe impact.
### Legal Issues Checklist
The goal of this checklist is to help expose legal issues that might
otherwise be missed. It does not help with the actual management of
legal issues.
*TODO: Answer the questions below. If multiple sample answers are
provided, delete the ones that do not apply. Edit any provided answers
as needed.*
#### Does the development organization hold trademarks on the product name and any other names used in marketing the product?
::Yes. Make sure to defend your ownership.
::No. Make sure not to impinge on the trademarks of others.
#### Does the development organization hold or license patents on intellectual property that is used in the product?
::Yes. Make sure to defend your ownership.
::No. Make sure not to impinge on the patents of others.
#### Does the development organization hold or license copyrights on source code that is used in the product?
::Yes. Make sure to defend your ownership.
::No. Make sure not to impinge on the patents of others.
#### For each component in the product, is that component being used in a way that complies with its license?
::Fill in details in table above.
#### For each piece of copyrighted data in the product, is that data being used in a way that complies with its license?
::Fill in details in table above.
#### Was any component or data produced by another organization under contract?
::Yes. Review the contract details for ownership and licensing.
::No. No action required.
#### Does the product use technologies that are under export control?
::Yes. But, we have no plans to export.
::Yes. Take steps to obtain needed export permissions.
::No. No action required.
#### Does the product need to meet industry-specific regulations?
::Yes. Take steps to meet them. Specifically...
::No. No action needed.
#### Does the product satisfy corporate policies (e.g., on privacy and security)?
::Yes. Describe how each policy is satisfied..
::No. Describe steps to bring the product into compliance.
::No. No policies apply.

73
ProductDocumentation/License.md Normal file
View File

@ -0,0 +1,73 @@
Do not modify or delete this file. This file describes the license under
which you may use the ReadySET templates.
### Copyright and License
Copyright (C) 2003-2004 Jason Robbins. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of these files must retain the above copyright notice, this list of conditions and the following disclaimer. The individual template files must retain the copyright footnote whenever they are used as templates.
2. The name "ReadySET" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact jrobbins@jrobbins.org.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
### License FAQ
---
#### Can I use these templates at my company?
Yes, absolutely. Once you fill in the template with detailed
information about a specific project, you are free to do what you
want with them in the context of that project. ***You may even hide the
template copyright statement***: the best way to do that is to edit the
file inst.css.
#### Can I modify these templates for use on several projects at my company?
Yes, absolutely. You may modify and distribute these templates to
others, so long as you retain this file and the footnote with the
copyright statement clearly visible in each file.
#### Can I include these templates as part of a commercial product?
If you use the templates and fill in details about a given product,
go ahead. If you are thinking of making a product that includes the
templates for use *as templates*, you must retain this file and the
copyright statement in a visible footnote. An enhanced commercial
version of these templates, [ReadySETPro](http://www.readysetpro.com/),
is already in development
#### Can I combine these templates with other templates or documents?
Sure, go ahead. This license is not "viral", it does not mean that
anything you do must be open source or covered under the
same license.
#### If I enhance the templates, must I give those enhancements back to the open source project?
No, but it would be very welcome. Even if you don't modify the
templates, you can share your "words of wisdom". For more
information on contributing, see the
[ReadySET home page](http://readyset.tigris.org/).
#### ReadySET seems too good to be true. What is the catch? Why would anyone buy a commercial version?
There is no catch. However, the scope of ReadySET is limited to only
most common needs of development projects. It is easy to get started
with ReadySET, but [ReadySET Pro](http://www.readysetpro.com/) holds
much more value for corporate users.

262
ProductDocumentation/Project-Plan.md Normal file
View File

@ -0,0 +1,262 @@
##### Project
::[PROJECT-NAME](Home)
##### Project Time-frame:
::START-DATE - END-DATE
##### Attached worksheets:
- Plan > [Resource Needs](Resource-Needs)
##### Related Documents
- [Project Proposal](Proposal) > [Target audience and benefits](Target-and-Benefits)
- [Software development methodology](SDM)
- [Glossary](Glossary)
---
**Process impact:** This plan will be used to evaluate and manage the
project. Key assumptions that affect the plan should be documented here.
The project plan should be updated throughout the life-time of the
project.
*TODO: Fill in the information above and below. Add or remove rows as
needed. Use the worksheet to help identify and scope resource needs.*
### Summary of Project
#### What are the business problem, scope, and goal of this project?
For a summary of this project, see the [Project proposal](Proposal).
#### Who will sponsor, manage, and lead the project?
- ::Sponsor: PERSON-NAME
- ::Manager: PERSON-NAME
- ::Technical lead: PERSON-NAME
#### What authority does the project manager have?
- ::Hire, dismiss, or reassign personnel in his/her department
- ::Hire contract employees or manage subcontractors
- ::Purchase equipment, software, and other needed capital
- ::Assign specific tasks to other departments
- ::Negotiate requirements and schedules with customers
- ::Negotiate with vendors, suppliers, and partners
#### What planning lessons were learned in previous releases?
::None yet. This is the first release.
- ::We can reduce training time, but it significantly increases development time.
- ::Maintaining a past release takes more than 20% of our time, due to low quality in that release.
- ::The customer seems to always change the requirements after the second demo.
- ::There are always defects. We planned time to test, but we forgot to plan time to fix the defects.
On this project, we will actually estimate the number of undetected defects.
- ::Issue XXXX made us realize that we forgot to plan time for DEVELOPMENT-TASK.
### Summary of Methodology
#### What general development approach will be used?
::THREE TO FIVE SENTENCES OR BULLETS HERE. COVER GENERAL APPROACH, IMPORTANT ASSUMPTIONS, KEY PRACTICES, AND PROJECT COORDINATION CONTROLS.
For more information see the [Software Development Methodology](SDM).
#### How will the project team be organized?
- ::The development team will consist of ...
- ::The change control board will consist of ...
#### What development and collaboration tools will be use?
::We plan to use the following tools extensively through out the project:
- ::Project website
- ::Project mailing lists
- ::Issue tracking system
- ::Version control system
- ::Automated build system
- ::Automated unit test system
#### How will changes be controlled?
- ::Requests for requirements changes will be tracked in the issue tracker
- ::The change control board ([CCB](Glossary#ccb)) will review requested changes and authorize work on them as appropriate
- ::After the [feature complete](Glossary#featurecomplete) milestone, no new features will be added to this release.
- ::After the [code complete](Glossary#codecomplete) milestone, no entirely new product source code will be added to this release.
- ::All source code commit log messages must refer to a specific issue ID, after the feature complete milestone.
#### How will this plan be updated?
::This project plan will be updated as needed throughout the project.
It will be placed under version control and instructions for
accessing it will be on the [project website](Home). Any
change to the plan will cause an automatic notification to be sent
to a project mailing list.
### Work Breakdown Structure and Estimates
*TODO: List tasks that will be needed for this project. Keep dividing
tasks into subtasks until you feel that you have enough detail to expose
risks and make reasonable estimates in ideal engineering hours.*
*TIP: Label each step uniquely to show its position in the WBS, e.g.,
Step 1.1.4.A. Use numbers for steps that you intend to do in sequence,
and use letters for steps that you intend to do in parallel. E.g., Step
1.1 comes before Steps 1.2.A and 1.2.B, but those two steps may be done
in parallel, and Step 1.3 will be done after all 1.2.\* steps have been
finished. Don't worry about renumbering if you delete a step.*
| Step | Description | Estimate |
|-----------|-----------------------------------------------------------|----------|
| 1. | ::Preparation | |
| 1.1. | ::Developer training | 30h |
| 2. | ::Inception | |
| 2.1. | ::Requirements gathering | 30h |
| 2.2. | ::Requirements specification | 20h |
| 2.3. | ::Requirements validation | 10h |
| 3. | ::Elaboration | |
| 3.1. | ::High-level design | 5h |
| 3.2. | ::Low-level design (break down by component) | |
| 3.2.A. | ::Object design | 10h |
| 3.2.B. | ::User interface design | 10h |
| 3.2.C. | ::Database design | 3h |
| 3.3. | ::Design review and evaluation | 5h |
| 4. | ::Construction | |
| 4.1.A. | ::System implementation | |
| 4.1.A.1. | ::Implement COMPONENT-NAME 1 | 25h |
| 4.1.A.2. | ::Implement COMPONENT-NAME 2 | 25h |
| 4.1.A.3. | ::Implement COMPONENT-NAME 3 | 25h |
| 4.1.A.4. | ::Implement COMPONENT-NAME 4 | 25h |
| 4.1.A.5. | ::Integrate Components (mostly done during implementation)| 5h |
| 4.1.B. | ::Technical documentation (break down by component) | 10h |
| 4.1.C. | ::User documentation (break down by component) | 10h |
| 4.1.D. | ::Testing | |
| 4.1.D.1. | ::Test planning | 10h |
| 4.1.D.2. | ::Test code implementation (break down by component) | 30h |
| 4.1.D.3. | ::Test execution | 10h |
| 4.2. | ::Implementation review and evaluation | 15h |
| 5. | ::Transition | |
| 5.A. | ::Release packaging | 3h |
| 5.B. | ::Documentation for other groups | 3h |
| 6. | ::Reflection | |
| 6.1. | ::Postmortem report | 10h |
| | ::Total | 329 hours|
### Deliverables in this Release
*TODO: List project deliverables in detail, with delivery dates.*
| Deliverable Name | Description | Delivery Date |
|------------------|---------------------------------------------------------------|---------------|
| Deliverable Name | ::Description | Delivery Date |
| Deliverable Name | ::Description | Delivery Date |
| Deliverable Name | ::Description Description Description Description Description | Delivery Date |
| Deliverable Name | ::Description | Delivery Date |
### Schedule for this Release
*TODO: Make the rows in this table match the steps in your WBS above. If
you have a large number of detailed steps, you can skip the most
detailed ones. The columns of the table represent weeks of calendar
time. For each cell in the table, enter the number of hours ideal
engineering time that the team will spend on that task that week. Total
your hours across and down.*
*TIP: These hours should total to the same as the total of the hours
listed in your [resource needs](Resource-Needs) document. And, the
hours for each type of effort resources needed should correspond to the
sum for each type of task.*
| Task \ Week | W-01 | W-02 | W-03 | W-04 | W-05 | W-06 | W-07 | W-08 | W-09 | W-10 | W-11 | W-12 | Task Total |
|-----------------|------|------|------|------|------|------|------|------|------|------|------|------|------------|
| ::1. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::2. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::3. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::4.1.A. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::4.1.B. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::4.1.C. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::4.1.D. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::4.2. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::5. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::6. | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
| ::Weekly Totals | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 | 00 |
### Risk Management
*TODO: List and rank the major risks of this project, and what you plan
to do to mitigate each risk. If you don't plan to do anything to
mitigate the risk, state that. Use the risk list below, or the [risks
worksheet](Risks).*
Please see the [risks worksheet](Risks).
#### The main risks of this project are
1. ::There is a potential conflict between the goals of a high-quality appearance and one that is completely customizable. We can only succeed if players find the web site appealing, and game vendors can customize it with no more effort than would be needed to build a static website. We already have a design in mind that will address this risk and we will review it with a web site designer who worked for a game vendor site.
2. ::There are significant technical difficulties in building a web site and web application. This will be a risk because one person on our team has much experience with the relevant tools and technologies. Although the others will learn, we will certainly make some mistakes and sub-optimal choices. We will address this risk by scoping the project such that we have enough time to train and to review the design and implementation.
3. ::The schedule for this project is very short. We will manage this by planning a conservatively scoped functional core and series of functional enhancements that can be individually slipped to later releases if needed.
4. ::The performance of the system will be significantly impacted by the decisions made during the [database design task](#3.2.C). None of our current team members has experience with database optimization. To address this, we will arrange a review meeting with an experienced DBA or hire a consultant from the database vendor.
5. ::We could be underestimating known tasks.
HOW TO AVOID/MITIGATE?
6. ::We could be underestimating the impact of unknown tasks.
HOW TO AVOID/MITIGATE?
7. ::We could be underestimating the dependencies between tasks.
HOW TO AVOID/MITIGATE?
8. ::We could have misunderstood the customer's requirements.
HOW TO AVOID/MITIGATE?
9. ::The customer could change the requirements.
HOW TO AVOID/MITIGATE?
10. ::We could face major difficulties with the technology chosen for this project.
HOW TO AVOID/MITIGATE?
11. ::We could have low quality that demands significant rework.
HOW TO AVOID/MITIGATE?
12. ::We could incorrectly assess our progress until it is too late to react.
HOW TO AVOID/MITIGATE?
13. ::We could lose resources. E.g., team members could get sick, spend time on other projects, or quit.
HOW TO AVOID/MITIGATE?
14. ::There may be a mis-alignment of stakeholder goals or expectations.
HOW TO AVOID/MITIGATE?
### Project Planning Dependencies
#### Does this project conflict or compete for resources with any other project?
::No, this is the only project that we are working on.
::Yes, and we have determined how many hours each person can actually
dedicate to this project.
#### Are the same human or machine resources allocated to maintenance of past versions and/or planning of future versions during this release time period?
::No, this is the first release and we will not plan the next release.
::Yes, we predict that team members will spend an average of 20% of
their time maintaining previous releases and planning future
releases during this release time frame. Some weeks may be higher if
an urgent patch to a previous release is needed.
#### Does this project depend on the success of any other project?
::No, this project stands alone.
::Yes, project P1 must provide library L, and project P2 must prove
the usability of feature F, and....
#### Does any other project depend on this project?
::No, project is not producing any components that will be used in
other current projects.
::Yes, we must produce library L for our project and support users of
L in projects P1 and P2.
#### Are there any other important dependencies that will affect this project?
::No, everything is covered above.
::Yes. DETAILS....

220
ProductDocumentation/Proposal.md Normal file
View File

@ -0,0 +1,220 @@
##### Project
::[PROJECT-NAME](Home)
##### Project Time-frame:
::2003/1/16 to 2003/3/19
##### Summary:
::2-4 SENTENCE SUMMARY
##### Attached Worksheets:
Project Proposal > [Target audience and benefits](Target-and-Benefits)
##### Related Documents
- [Project plan](Project-Plan) > [Resource needs](Resource-Needs)
- [Glossary](Glossary)
---
**Process impact:** This proposal, along with drafts of related
documents, will be used by management to determine whether or not to
approve 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.
### Background and Motivation
*TODO: Replace the example text below with text that describes your
project. What are the needs or problems that you are trying to address?
Why do these needs (still) exist? Why are these problems worth solving?
Who is the customer? Write 2-4 paragraphs.*
#### What is the setting and history behind this project?
::Video games were originally designed and built as stand-alone
systems with the user playing against the machine. Although many
advances have been made in game AI, humans still tend to enjoy
competing against other humans over a network. There is a social
aspect to network gaming where people form teams that play and
leagues that play at scheduled times and keep scores over a
prolonged period. This is important to video game vendors because it
can result in increased revenue and extend the sales life of
their products.
#### What is the problem to be addressed?
::There are 100 million users on the Internet, and hundreds of
websites dedicated to video game playing teams, called "clans". If
users have to explore to find the good clans that they can join, it
takes a lot of their time. There is a need for a faster way for
users to find high quality clan websites that interest them and that
will allow them to join.
#### What are some current approaches to this problem?
::Users can tell each other about clan websites, but that is not
scalable because it depends on manual steps by people who may not be
motivated or honest in their evaluations. There are already some
clan directory web sites, but they are not automated so they are
always out of date and do not rate the quality of the websites.
- ::[Example of current manually maintained clan website](#)
- ::[Link to existing competitor](#)
#### Why is this problem worth solving or worth solving better?
::A better clan directory service would be valuable because it could
greatly increase player satisfaction and allow them to spend more
time playing and less time searching. Implementing a better clan
directory would cause players to use that website rather than the
existing directories. The benefit to us could come in the form of
revenue from advertising and service fees from video game vendors.
#### How will this product be better than previous approaches?
::We add innovative new features. Our affiliate directory will be
larger an more detailed. We will offer built-in tools for managing
membership and organizing events such as game nights or tournaments.
::Our system will have similar functionality, but it will have much
better maintainability, scalability, and security.
::Our system will have similar functionality, but it is specifically
aimed at a market segment that is not served by competing products.
::This is a "me-too" product that will go head-to-head with very
similar competing products in the same market. The market is large
enough that we can be very happy with a share of it. Our unique
competitive advantages are in non-product area of our business such
as sales, marketing, partnerships, support, training, etc. The
product will have some simple built-in "hooks" that leverage
those advantages.
#### Where is there more information on this problem?
::The following pages provide additional background and motivation:
- ::[Magazine article on this topic](#)
- ::[Industry analysis's report on massive-multi-player game market](#)
- ::[Quotes from game players](#)
### Goal
#### What is the goal of this project?
::This project will produce an engine for clan directory websites that
allows players to quickly find, evaluate, and join clans.
#### What are the defining features and benefits of this product?
- ::Reusable website engine with functionality for creating,
editing, deleting, searching, categorizing, browsing, rating,
and commenting on clans. This automates all clan operations and
ensures that users will always find information that is
automatically up-to-date.
- ::The reusable website engine will have a highly configurable
appearance that allows it to match the look and feel of the
game. This allows the reusable website engine to have a
high-quality appearance that is just as good as existing
clan directories.
- ::The website engine will be secure and only allow users with the
proper permissions to edit, delete, or join a clan. This will
prevent cheating or the submission of false information.
#### Where are other documents that further explain the goal of this project?
- ::[Mock-up](LINK-TO-MOCKUP)
- ::[Early user stories](LINK-TO-EARLY-STORIES)
- ::[Quotes from potential customers](LINK-TO-QUOTES)
- ::[Comparison to existing competitors](LINK-TO-COMPARISON)
- ::[Draft feature list](LINK-TO-DRAFT-FEATURES)
### Scope
*TODO: Replace the sample text below with a clear statement of the scope
of your project. What are the high-level things that you plan to do, and
that you will not do? What are your important simplifying assumptions?
Try to guard against reasonable misunderstandings that might arise if
you did not explain the scope. It can take the form of a paragraph,
bullet list, in/out list, and/or UML context diagram.*
::We want to focus on the web application itself, and the features of that
application that help build a good gaming community.
::See the [context diagram](LINK-TO-CONTEXT-DIAGRAM).
- ::Work with common servers and browsers that we are already
familiar with.
- ::Allow easy customizations of fonts and colors, with the same basic
page layout.
- ::Enough security to greatly discourage abuse
- ::The web site content discusses a game, but it will not need to
actually integrate with any game software
| In Scope | Out of Scope |
|----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ::Building a web application for use with standard web servers and application servers | ::Building a new web server or application server |
| ::Working the most popular browsers (IE6, NN7/Mozilla) | ::Working with uncommon or outdated browsers |
| ::Security in the form of user accounts, passwords, and permissions | ::Special security against hackers. Finding or patching security holes in existing software components. |
| ::One simple sample look-and-feel and instructions for customization | ::Our own high-quality look-and-feel. A library of look-and-feel options. |
| ::Database and server load and data volume that can be handled by one computer. | ::Managing a cluster of servers. |
| ::Keeping track of which users are in which clans | ::Tracking all user activity on the site and producing custom reports |
| ::Displaying advertisements to visitors. Billing advertisers for impressions. | ::Automatically selecting ads that fit the visitor's interests. On-line management of advertising or real-time reporting to advertisers. Participating in existing banner advertising affiliate networks. |
### Deliverables
*TODO: Briefly list project deliverables. When you are done, what will
you deliver to the customer? This can be copied from the draft project
plan and simplified to reduce technical detail.*
- ::Clan website directory engine
- ::Customization guide
- ::Sample look-and-feel
- ::On-line help for end users
- ::Command-line advertising configuration tool and report generator
### Risks and Rewards
#### What are the main risks of this project?
1. ::There is a potential conflict between the goals of a
high-quality appearance and one that is completely customizable.
We can only succeed if players find the web site appealing, and
game vendors can customize it with no more effort than would be
needed to build a static website. We already have a design in
mind that will address this risk and we will review it with a
web site designer who worked for a game vendor site.
2. ::There are significant technical difficulties in building a web
site and web application. This will be a risk because one person
on our team has much experience with the relevant tools
and technologies. Although the others will learn, we will
certainly make some mistakes and sub-optimal choices. We will
address this risk by scoping the project such that we have
enough time to train and to review the design
and implementation.
3. ::The schedule for this project is very short. We will manage this
by planning a conservatively scoped functional core and series
of functional enhancements that can be individually slipped to
later releases if needed.
#### What are the main rewards if this project succeeds?
::If we accomplish the elements of our plan, our clan directory
website engine will replace existing clan directory websites and
generate traffic which will result in advertising revenue and/or
hosting fees paid by game vendors. Our ability to overcome the
challenges above will determine time to market, the speed of
adoption, the amount of web traffic, and thus the generated revenue
over time.
### Project Plan
See attached draft of [project plan](Project-Plan)
and [resource needs](Resource-Needs).

304
ProductDocumentation/QA-Plan.md Normal file
View File

@ -0,0 +1,304 @@
*TODO: For each release, update this file by filling in answers to the
questions. In cases where multiple answers are already written, delete
those answers that do not apply.*
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number:
::X.Y.Z
##### Release Audience:
- ::General availability release ||
- ::Customer-specific release: CUSTOMER(S) ||
- ::Developer release (Internal usage only) ||
- ::Early access release (Controlled external access)
##### Attached Worksheets:
- QA plan > [Review meeting notes](Review-Meeting-Notes)
- QA plan > [System test case suite](Test-Suite)
- QA plan > [System test runs](Test-Run-Suite)
##### Related Documents
- [Software Requirements Specification](SRS)
- [Design](Design)
- [Project plan](Project-Plan)
- [Software development methodology](SDM)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
**Process impact:** This document specifies quality goals, selects
strategies for assuring that those goals have been met, and details a
plan of action to carry out those strategies.
### Introduction
#### Why is this QA plan needed?
::"Quality" refers to all the good things that we would like to see in
our product. We build a quality product and assure its quality by
keeping quality in mind all the time and performing the selected
activities below. Testing is one QA activity, but it is not the best
or only one, other QA activities include the use of style guides and
checklists, review meetings, use of analysis tools, and careful
quality measurements and estimates. A plan is needed to select and
coordinate all the QA activities.
#### What QA lessons were learned in previous releases?
::None yet. This is the first release.
- ::Different browsers render the same HTML page differently, so we
must test each version of each supported browser.
- ::In a previous release, customers found that punctuation (e.g.,
quotation marks and less-than signs) were entered and processed
properly, but not displayed properly. From now on, we must test
both validation and display of special characters.
- ::Large data sets can sometimes make our system fail if the space
used for temporary data is used up. Our test plans should
include more data volume tests.
#### What is the scope of this QA plan?
::All components and aspects of the system will be evaluated in
this release.
::There are many quality goals and approaches to assuring them. Since
we have limited time and resources for this release, we will focus
on the following components and aspects:
- ::COMPONENT-1
- ::COMPONENT-2
- ::COMPONENT-3
- ::FEATURE-1
- ::FEATURE-2
#### What is the summary of this plan?
::In this release we will continue to use development practices that
support all of our quality goals, but we will focus on functional
correctness and robustness. We will do that with the following major
activities:
- ::using if-statements to test preconditions and assert statements
to test invariants and post-conditions
- ::conducting frequent reviews
- ::performing automated unit and regression testing with JUnit
- ::carrying out structured manual system testing
- ::keeping all issues up-to-date in an issue tracking database
### Quality Goals for this Release
*TODO: Add or edit goals to fit your project. Group them by priorities
that make sense for your project on this particular release.*
- ::Essential
- [Functionality > Correctness](Glossary-Standard-Terms#functionality--correctness)
- [Functionality > Robustness](Glossary-Standard-Terms#functionality--robustness)
- ::Expected
- [Functionality > Accuracy](Glossary-Standard-Terms#functionality--accuracy)
- [Functionality > Compatibility](Glossary-Standard-Terms#functionality--compatibility)
- [Functionality > Factual correctness](Glossary-Standard-Terms#functionality--factual-correctness)
- [Usability > Understandability and Readability](Glossary-Standard-Terms#usability--understandability-and-readability)
- [Usability > Learnability and Memorability](Glossary-Standard-Terms#usability--learnability-and-memorability)
- [Usability > Task support](Glossary-Standard-Terms#usability--task-support)
- [Usability > Efficiency](Glossary-Standard-Terms#usability--efficiency)
- [Usability > Safety](Glossary-Standard-Terms#usability--safety)
- [Usability > Consistency and Familiarity](Glossary-Standard-Terms#usability--consistency-and-familiarity)
- [Usability > Subjective satisfaction](Glossary-Standard-Terms#usability--subjective-satisfaction)
- [Security](Glossary-Standard-Terms#security)
- ::Desired
- [Reliability > Consistency under load](Glossary-Standard-Terms#reliability--consistency-under-load)
- [Reliability > Consistency under concurrency](Glossary-Standard-Terms#reliability--consistency-under-concurrency)
- [Reliability > Availability under load](Glossary-Standard-Terms#reliability--availability-under-load)
- [Reliability > Longevity](Glossary-Standard-Terms#reliability--longevity)
- [Efficiency](Glossary-Standard-Terms#efficiency)
- [Scalability](Glossary-Standard-Terms#scalability)
- [Scalability > Performance under load](Glossary-Standard-Terms#scalability--performance-under-load)
- [Scalability > Large data volume](Glossary-Standard-Terms#scalability--large-data-volume)
- [Operability](Glossary-Standard-Terms#operability)
- [Maintainability > Understandability](Glossary-Standard-Terms#maintainability--understandability)
- [Maintainability > Evolvability](Glossary-Standard-Terms#maintainability--evolvability)
- [Maintainability > Testability](Glossary-Standard-Terms#maintainability--testability)
### QA Strategy
*TODO: Consider the activities listed below and delete those that are not
applicable to your project. Edit and add new activities if needed. For
each activity, specify the coverage or frequency that you plan to
achieve. If you do not plan to perform an activity, write "N/A".*
<!-- Hint: view this large table with text wrapping turned off -->
| Activity | Coverage or Frequency | Description |
|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ::Preconditions | <ul><li>::Every public method</li><li>::Every public method in COMPONENT-NAME</li><li>::All public methods that modify data</li></ul> | ::We will use if-statements at the beginning of public methods to validate each argument value. This helps to document assumptions and catch invalid values before they can cause faults. |
| ::Assertions | <ul><li>::Every private method</li><li>::Every private method in COMPONENT-NAME</li><li>::All private methods that modify data</li></ul> | ::Assertions will be used to validate all arguments to private methods. Since these methods are only called from our other methods, arguments passed to them should always be valid, unless our code is defective. Assertions will also be used to test class invariants and some postconditions. |
| ::Static analysis | <ul><li>::Strict compiler warnings</li><li>::Automated style checking</li><li>::XML validation</li><li>Detetect common errors</li></ul> | ::We will use source code analysis tools to automatically detect errors. Style checkers will help make all of our code consistent with our coding standards. XML validation ensures that each XML document conforms to its DTD. Lint-like tools help detect common programming errors. E.g.: [lint](http://www.freebsd.org/cgi/man.cgi?query=lint), [lclint/splint](http://www.splint.org/), [jlint](http://artho.com/jlint/), [checkstyle](http://sourceforge.net/projects/checkstyle/), [Jcsc](http://sourceforge.net/projects/jcsc), [PyLint](https://www.pylint.org/), [PyChecker](http://pychecker.sourceforge.net/), [Tidy](http://www.html-tidy.org/) |
| ::Buddy review | <ul><li>::All changes to release branches</li><li>::All changes to COMPONENT-NAME</li><li>::All changes</li></ul> | ::Whenever changes must be made to code on a release branch (e.g., to prepare a maintenance release) the change will be reviewed by another developer before it is committed. The goal is to make sure that fixes do not introduce new defects. |
| ::Review meetings | <ul><li>::Weekly</li><li>::Once before release</li><li>::Every source file</li></ul> | ::We will hold review meetings where developers will perform formal inspections of selected code or documents. We choose to spend a small, predetermined amount of time and try to maximize the results by selecting review documents carefully. In the review process we will use and maintain a variety of checklists. |
| ::Unit testing | <ul><li>::100% of public methods, and 75% of statements</li><li>::100% of public methods</li><li>::75% of statements</li></ul> | ::We will develop and maintain a unit test suite using the JUnit framework. We will consider the boundary conditions for each argument and test both sides of each boundary. Tests must be run and passed before each commit, and they will also be run by the testing team. Each public method will have at least one test. And, the overall test suite will exercise at least 75% of all executable statements in the system. |
| ::Manual system testing | <ul><li>::100% of UI screens and fields</li><li>::100% of specified requirements</li></ul> | ::The QA team will author and maintain a detailed written suite of manual tests to test the entire system through the user interface. This plan will be detailed enough that a person could repeatably carry out the tests from the test suite document and other associated documents. |
| ::Automated system testing | <ul><li>::100% of UI screens and fields</li><li>::100% of specified requirements</li></ul> | ::The QA team will use a system test automation tool to author and maintain a suite of test scripts to test the entire system through the user interface. |
| ::Regression testing | <ul><li>::Run all unit tests before each commit</li><li>::Run all unit tests nightly</li><li>::Add new unit test when verifying fixes</li></ul> | ::We will adopt a policy of frequently re-running all automated tests, including those that have previously been successful. This will help catch regressions (bugs that we thought were fixed, but that appear again). |
| ::Load, stress, and capacity testing | <ul><li>::Simple load testing</li><li>::Detailed analysis of each scalability parameter</li></ul> | ::We use a load testing tool and/or custom scripts to simulate heavy usage of the system. Load will be defined by scalability parameters such as number of concurrent users, number of transactions per second, or number/size of data items stored/processed. We will verify that the system can handle loads within its capacity without crashing, producing incorrect results, mixing up results for distinct users, or corrupting the data. We will verify that when capacity limits are exceeded, the system safely rejects, ignores, or defers requests that it cannot handle. |
| ::Beta testing | <ul><li>::4 current customers</li><li>::40 members of our developers network</li><li>::1000 members of the public</li></ul> | ::We will involve outsiders in a beta test, or early access, program. We will beta testers directions to focus on specific features of the system. We will actively follow up with beta testers to encourage them to report issues. |
| ::Instrumentation and monitoring | <ul><li>::Monitor our ASP servers</li><li>::Remotely monitor customer servers</li></ul> | ::As part of our SLA, we will monitor the behavior of servers to automatically detect service outages or performance degradation. We have policies and procedures in place for failure notification, escalation, and correction. |
| ::Field failure reports | <ul><li>::Prompt users to report failures</li><li>::Automatically report failures</li></ul> | ::We want to understand each post-deployment system failure and actively take steps to correct the defect. The system has built-in capabilities for gathering detailed information from each system failure (e.g., error message, stack traceback, operating system version). This information will be transmitted back to us so that we may analyze it and act on it. |
### QA Strategy Evaluation
*TODO: Use the following table to evaluate how well your QA Strategy will
assure your QA goals.*
| Goal | Preconditions | Assertions | Buddy review | Review meeting | Unit testing | Manual system testing | Overall assurance |
|-----------------|-----------------|--------------|----------------|------------------|----------------|-------------------------|---------------------|
| Functionality | ::Medium | ::Medium | ::Medium | ::High | ::High | ::High | ::Strong |
| Correctness | ::High | ::High | ::Medium | ::Medium | ::High | ::Medium | ::Strong |
| Robustness | ::High | ::High | ::Medium | ::Medium | ::High | ::Medium | ::Strong |
| Usability | ::None | ::None | ::None | ::High | ::None | ::Medium | ::Strong |
| Security | ::Medium | ::None | ::Medium | ::High | ::None | ::Medium | ::Strong |
| Reliability | ::None | ::Medium | ::Low | ::Medium | ::Medium | ::Medium | ::Weak |
| Efficiency | ::None | ::None | ::Low | ::Medium | ::None | ::Low | ::At-Risk |
| Scalability | ::None | ::None | ::Low | ::Medium | ::Low | ::Low | ::At-Risk |
| Operability | ::None | ::None | ::None | ::Low | ::None | ::Low | ::At-Risk |
| Maintainability | ::Medium | ::Low | ::Medium | ::High | ::Low | ::None | ::Weak |
Cell values in the table above are subjective estimates of the
effectiveness of each activity. This table helps to identify quality
goals that are not being adequately assured.
#### Evaluation cell values
- High: This activity gives a strong assurance that the goal has been
met in development.
- Medium: This activity gives a medium assurance that the goal has
been met in development.
- Low: This activity gives only a little assurance that the goal has
been met in development.
- None: This activity does not address the goal.
#### Overall assurance values
- Strong: The set of activities together provide strong assurance that
the goal has been met in development.
- Weak: The activities together provide limited assurance that the
goal has been met in development.
- At-Risk: There is little or no assurance that this goal has
been met.
Note: As a rule of thumb, it takes at least two "high" activities and
one "medium" to give a "strong" overall rating. Likewise, it takes at
least two "medium" and one "low" activities to rate a "weak" overall
rating.
### Plan of Action
*TODO: Adjust this plan to fit your project.*
*TODO: Once the plan is outlined, tasks should be assigned to individuals
and tracked to completion.*
1. Preconditions and Assertions
- ::Refine requirements document whenever preconditions are not
already determined
- ::Create validation functions for use by preconditions and
assertions, as needed
- ::Write preconditions and assertions in code
2. Review meetings
- ::Assign buddy reviewers whenever a change to a release branch is
considered
- ::Select an at-risk document or section of code for weekly review
meetings
- ::Each week, identify reviewers and schedule review meetings
- ::Reviewers study the material individually for 2 hours
- ::Reviewers meet to inspect the material for 2 hours
- ::Place [review meeting notes](Review-Meeting-Notes) in the
repository and track any issues identified in review meetings
3. Unit tests
- ::Set up infrastructure for easy execution of JUnit tests (this is
just an Ant target)
- ::Create unit tests for each class when the class is created
- ::Execute unit tests before each commit. All tests must pass
before developer can commit, otherwise open new issue(s) for
failed tests. These "smoke tests" will be executed in each
developer's normal development environment.
- ::Execute unit tests completely on each release candidate to check
for regressions. These regression tests will be executed on a
dedicated QA machine.
- ::Update unit tests whenever requirements change
4. System tests
- ::Design and specify a detailed manual [test suite](Test-Suite).
- ::Review the system test suite to make sure that every UI screen
and element is covered
- ::Execute system tests completely on each release candidate. These
system tests will be carried out on a dedicated QA machine.
- ::Update system tests whenever requirements change
5. QA Management
- ::Update this test plan whenever requirements change
- ::Document test results and communicate them to the entire
development team
- ::Estimate remaining (not yet detected) defects based on current
issue tracking data, defect rates, and metrics on code size and
the impact of changes.
- ::Keep all issues up-to-date in an issue tracking database. The
issue tracker is available to all project members
[here](LINK-TO-ISSUE-TRACKER). The meaning of issue states,
priorities, and other attributes are defined in the
[SDM](SDM#issue-tracking).
### QA-Plan Checklist
#### Do the selected activities in the QA Strategy provide enough assurance that the project will meet it's quality goals?
::Yes, if all activities are carried out as planned, we are confident
that the quality goals will be satisfied. We will, of course, adjust
this plan as needed.
::No, this plan leaves open several quality risks that have been noted
in the [Risk Management](Project-Plan#Risk-Management) section of the
[Project Plan](Project-Plan).
#### Have human resources been allocated to carry out the QA activities?
::Yes, human resources have been allocated. They are listed in the
[Resource Needs](Resource-Needs) document.
::No, human resources have not been allocated. They are listed as
"pending" in the [Resource Needs](Resource-Needs) document.
#### Have machine and software resources been allocated as needed for the QA activities?
::Yes, the QA team will use desktop machines and servers that are
already allocated to them.
::Yes, a QA Lab has been set up. The needed machine and software
resources are listed in the [Resource Needs](Resource-Needs) document.
::No, needed machine and software resources are listed as pending in
the [Resource Needs](Resource-Needs) document.
#### Has this QA Plan been communicated to the development team and other stakeholders?
::Yes, everyone is aware of our prioritized quality goals for this
release and understands how their work will help achieve
those goals. Feedback is welcome.
::Yes, this document is being posted to the project website. Feedback
is welcome.
::No, some developers are not aware of the quality goals and planned
QA activities for this release. This is a risk that is noted in the
[Risk Management](Project-Plan#Risk-Management) section of the
[Project Plan](Project-Plan).

133
ProductDocumentation/Release-Checklist.md Normal file
View File

@ -0,0 +1,133 @@
*TODO: For each release, copy this file and fill in answers to the
questions. In cases where multiple answers are already written, delete
those answers that do not apply.*
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### External release number
::X.Y.Z
##### Release audience
- ::General availability release
- ::Customer-specific release: CUSTOMER(S)
- ::Developer release (Internal usage only)
- ::Early access release (Controlled external access)
---
**Process impact:** 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.
*TODO: Discuss each item with the relevant stakeholders and update its
status. Add comments as needed to record important decisions or link to
resulting documents. Add new items as needed for your particular project
or process. Any uncovered problems or tasks should be tracked in the
issue tracker.*
### Marketing / Product Management
| Item | Status | Comments |
|--------------------------------------------------------------------------|---------|----------|
| ::All new requirements for this release have been tracked | Pending | |
| ::All prior defects needing resolution in this release have been tracked | Pending | |
| ::All marketing documents have been updated | Pending | |
| ::Marketing / Product Management is satisfied with this release | Pending | |
### Development
| Item | Status | Comments |
|--------------------------------------------------------|---------|----------|
| ::All needed design work has been completed | Pending | |
| ::All needed design work has been reviewed | Pending | |
| ::All development work has been completed | Pending | |
| ::All development work has been reviewed | Pending | |
| ::All defects assigned to this release have been fixed | Pending | |
| ::All development documentation has been updated | Pending | |
| ::All unit test code has been updated | Pending | |
| ::The development team is satisfied with this release | Pending | |
### Quality Assurance {#quality-assurance}
| Item | Status | Comments |
|-------------------------------------------------|---------|----------|
| ::The QA plan and test cases have been updated | Pending | |
| ::The QA plan has been completely carried out | Pending | |
| ::All discovered defects have been tracked | Pending | |
| ::All fixed defects have been verified as fixed | Pending | |
| ::The QA team is satisfied with this release | Pending | |
### Release Engineering / Configuration Management
| Item | Status | Comments |
|----------------------------------------------------------------------------------------------------------------------|---------|----------|
| ::All components have been properly tagged for release, and the release configuration is clearly defined | Pending | |
| ::Change-control practices have been followed, meaning that the released product does not contain unapproved changes | Pending | |
| ::The RelEng team is satisfied with this release | Pending | |
### User Experience
| Item | Status | Comments |
|-----------------------------------------------------------|---------|----------|
| ::Any new or changed functionality is deemed usable | Pending | |
| ::On-line and printed user documentation has been updated | Pending | |
| ::The UE team is satisfied with this release | Pending | |
### Technical Support / Operations
| Item | Status | Comments |
|--------------------------------------------------------------------------------------------------------------|---------|----------|
| ::Theory of operations document has been updated | Pending | |
| ::Tech support / Operations has successfully installed, upgraded, and used this release | Pending | |
| ::Any "Early access" or "Beta" program was conducted successfully and all resulting issues have been tracked | Pending | |
| ::The impact of any changes on operations offerings has been identified and tracked | Pending | |
| ::Troubleshooting guide has been updated | Pending | |
| ::The tech support / operations teams are satisfied with this release | Pending | |
### Services / Training
| Item | Status | Comments |
|----------------------------------------------------------------------------------|---------|----------|
| ::Services / Training has had access to this release | Pending | |
| ::The impact of any changes on service offerings has been identified and tracked | Pending | |
| ::Training materials have been updated | Pending | |
| ::Services / Training is satisfied with this release | Pending | |
### Legal
| Item | Status | Comments |
|-------------------------------------------------------------------------------|---------|----------|
| ::Legal risks associated with this release have been identified and tracked | Pending | |
| ::We hold proper licenses for all reused components and intellectual property | Pending | |
| ::We conform to all relevant laws and regulations (e.g., export, safety) | Pending | |
| ::The legal team is satisfied with this release | Pending | |
#### Possible status values
- Pending: Work still needs to be done
- N/A: This item cannot logically apply
- Waived: This item could apply, but the stakeholders deem it
unimportant
- Done: The stakeholders agree that the item has been satisfied
- Failed: This item has forced us to abandon this release
*TIP: If a stakeholder hits difficulties with this release after it goes
out, add those issues to the checklist template so that everyone knows
that they will be explicitly managed on the next release. Conduct a
postmortem review to help expose difficulties rather than repeat them.*
*TIP: You might consider some of the following additional stakeholders at
your organization: Other engineering groups (i.e., hardware design),
Manufacturing and Shipping, Software Process Improvement, Key customers
and partners, External developers, Risk Management, Business
Development, and Upper Management.*

174
ProductDocumentation/Release-Notes.md Normal file
View File

@ -0,0 +1,174 @@
*TODO: For each release, copy this file and fill in the needed
information.*
*TODO: Make sure to use the **product** name and **external** release
number, not internal information.*
##### Product
::[PRODUCT-NAME](http://www.COMPANY.com/products/PRODUCT-NAME/)
##### Release Number
::X.Y.Z
##### Release Date
::YEAR/MONTH/DAY
##### Customer Support
::For more information or support, please visit our
[website](http://www.COMPANY.com/products/PRODUCT-NAME/) or email us
at <support@COMPANY.com>
---
### Introduction
::This document contains the release notes for PRODUCT-NAME version X.Y.Z.
The following sections describe the release in detail and provide
late-breaking or other information that supplements the main
documentation.
*TODO: Consider using one of the following example paragraphs.*
::This is a developer release for internal evaluation only. Please report
any issues via the internal issue tracker.
::This is an early access release for evaluation and usage by select
partners. Your feedback is important to us, please help us make this the
best product possible.
::This is an early access release for wide evaluation and usage. Your
feedback is important to us, please help us make this the best product
possible. Keep in mind that we are continuing to work on PRODUCT-NAME and
things may change in the future.
::This is the first full release of this product. See the product website
for a complete description.
::(WHEN X IN VERSION NUMBER CHANGES) This is a major release with many new
features. Users of previous releases should check the "Version
Compatibility" section below for instructions on how to use existing
data with this new release.
::(WHEN Y IN VERSION NUMBER CHANGES) This is an upgrade release with some
significant enhancements. Users of previous releases are encouraged to
upgrade.
::(WHEN Z IN VERSION NUMBER CHANGES) This is a maintenance release that
improves quality, reliability, and performance without adding any new
functionality. All users of previous X.Y releases should upgrade to this
release.
::(WHEN DEFECT CORRECTION CLOSES SIGNIFICANT SECURITY HOLES) This is a
critical upgrade release that addresses recently discovered security
holes. All users of previous X.Y releases should upgrade immediately to
this release.
### What's New?
*TODO: Briefly list major user-visible enhancements. Or, note that
nothing major has been added. Technical issues should only be mentioned
if this is a reusable software component that will be used to build
larger products. Do not include issue numbers. Links to detailed
information can be helpful.*
- ::Added 4 new play-back modes
- ::Increased play-back speed by as much as 30%
- ::(FOR REUSABLE COMPONENTS ONLY) Streamlined build process
- ::(FOR REUSABLE COMPONENTS ONLY) Roughly doubled unit test coverage
- ::Many improvements to the product's quality, reliability, ease of
use, and performance. See "Recent Changes" below for details.
### Installation and Upgrade Notes
*TODO: Fill in these sections. The text here is only an example.*
#### ::Installation
::See the [installation instructions](Installation-Guide) for full details.
Please note that in this release, ...
::IMPORTANT: You must completely uninstall any previous "developer
release" or "early access" version of this product before installing
this release.
#### ::Manifest
::This release consists of the following items:
- ::Release notes (this file)
- ::Installation instructions / Quick start guide
- ::Product installer binary
- ::User guide
- ::Product source code and build instructions
### ::Minimum System Requirements
#### ::System Processor
::800MHz
#### ::System Memory
::256MB
#### ::Free Disk Space
::10MB
#### ::Operating System
::Windows 2000, Windows XP, Mac OS X, Linux (kernel 2.4)
#### ::Networking
::Internet access
#### ::Existing Software
- ::Standard e-mail client
- ::Popular web browser (IE6, NN7)
- ::SuperWaveEdit(TM) 2.0.2 (Needed for custom playback modes)
#### ::Version Compatibility
::Files saved by earlier versions of this product may be used with
this version. However, wave files saved in version W.Y.Z, must be
updated by using the WaveUpgrade utility.
### Recent Changes
*TODO: Query your public issue tracking system to produce a report of
changes in this release. Include the issue number, type, and one-line
summary. Include issues that were highlighted in the "What's New?"
section above. You may revise one-line summaries in the issue tracker,
prior to generating the report, if you notice that they are incorrect.
You may exclude or summarize changes that might give away valuable
proprietary information.*
- ::FIX [09823](#) Screen frozen when caps-lock is on
- ::FIX [09912](#) Static heard while downloading
- ::FIX [10923](#) Repeat-mode cannot play more than 99 times
- ::ENHANCEMENT [08237](#) Scratch DJ-mode
- ::ENHANCEMENT [08238](#) Chill DJ-mode
- ::ENHANCEMENT [08259](#) Retro stereo-mode
- ::ENHANCEMENT [10202](#) Techno-mode
### Known Problems and Workarounds
*TODO: Query your public issue tracking system to produce a report of
defects discovered in this release, or in previous releases that are
still not resolved. Include information on workarounds from the issues.
Otherwise, same as above.*
- ::DEFECT [07293](#) Player skips on very loud playback.
- ::WORKAROUND: Limit volume to settings 1 through 9.
- ::DEFECT [10509](#) Cannot switch directly from random play mode to
Internet play-list.
- ::WORKAROUND: Switch to local play-list first. Click [here](#) for
detailed instructions.
- ::DEFECT [10589](#) Static heard while booting
- ::DEFECT [10944](#) Repeat-mode cannot play more than 999 times

298
ProductDocumentation/Resource-Needs.md Normal file
View File

@ -0,0 +1,298 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Project Time-frame:
::START-DATE - END-DATE
##### Related Documents
- [Project proposal](Proposal)
- [Project plan](Project-Plan)
- [QA plan](QA-Plan)
- [Software development methodology](SDM)
- [Glossary](Glossary)
---
**Process impact:** 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 scope of the release should be
reconsidered or the process must be changed.
*TODO: Fill in the information above and below. Add or remove rows as
needed. Use the worksheet to help identify and scope resource needs.
These rows are just examples. The total effort listed in this example
may not even match the totals given in other examples of related
documents.*
### Human Resource Needs
| Need | Resource | Amount | Status | Comments/Responsibilities |
|-------------------------------------------|--------------------------------------|------------|------------|---------------------------|
| ::Project Management | ::PERSON-NAME | ::20 hours | ::Pending | |
| ::Requirements | ::PERSON-NAME | ::20 hours | ::Assigned | |
| ::Requirements | ::PERSON-NAME, PERSON-NAME, PERSON-NAME | ::10 hours | ::Assigned | |
| ::Consultation with domain expert | ::PERSON-NAME | ::2 hours | ::Pending | |
| ::Consultation with topic expert | ::PERSON-NAME | ::4 hours | ::Pending | |
| ::Training on use of component/technology | ::PERSON-NAME | ::8 hours | ::Assigned | |
| ::Overall Design | ::PERSON-NAME, PERSON-NAME, PERSON-NAME | ::20 hours | ::Assigned | |
| ::Detailed UI Design | ::PERSON-NAME | ::5 hours | ::Pending | |
| ::Detailed Database Design | ::PERSON-NAME | ::5 hours | ::Pending | |
| ::Development | ::PERSON-NAME, PERSON-NAME, PERSON-NAME | ::40 hours | ::Assigned | |
| ::Development | ::PERSON-NAME, PERSON-NAME | ::80 hours | ::Assigned | |
| ::Development | ::PERSON-NAME | ::20 hours | ::Pending | |
| ::Technical writing | ::PERSON-NAME, PERSON-NAME | ::10 hours | ::Assigned | |
| ::QA Planning | ::PERSON-NAME | ::10 hours | ::Assigned | |
| ::QA Testing | ::PERSON-NAME, PERSON-NAME, PERSON-NAME | ::40 hours | ::Assigned | |
| ::Release Engineering | ::PERSON-NAME | ::4 hours | ::Assigned | |
### Capital Needs
| Need | Resource | Amount | Status | Comments |
|------------------------------------|-------------------------------------------------------|-----------|---------------------------|---------------------------------------------------------------------------------|
| ::Training materials | ::Book/Course on specific technology | ::1 | ::Allocated | ::Book ordered |
| ::Development Workstations | ::800MHz PC, 256MB RAM | ::4 | ::Satisfied | ::Dev group will use existing workstations |
| ::Development DB Server | ::Dual CPU 1GHz PC, 512MB RAM: SERVERNAME.company.com | ::1 | ::Allocated | |
| ::Interactive Testing Workstations | ::800MHz PC, 256MB RAM | ::2 | ::Allocated | |
| ::Load Test Server | ::800MHz PC, 256MB RAM: SERVERNAME.company.com | ::1 | ::Pending | |
| ::Load Test Clients | ::500MHz PC or Mac, 128MB RAM | ::4 | ::Satisfied | ::QA group will use existing machines |
| ::Automated Testing Slave | ::800MHz PC, 256MB RAM: SERVERNAME.company.com | ::1 | ::Satisfied | ::QA group will use existing machine |
| ::Testing DB Server | ::Dual CPU 1GHz PC, 512MB RAM: SERVERNAME.company.com | ::1 | ::Rejected | ::Testing group will use development DB server and do load testing in off hours |
| ::IDE Licenses | ::Standard development licenses | ::N/A | ::Satisfied | ::Will use open source tools |
| ::SCM Licenses | ::Standard development licenses | ::N/A | ::Satisfied | ::Will use open source tools |
| ::Testing Tool Licenses | ::Standard development licenses | ::N/A | ::Satisfied | ::Will use open source tools |
| ::DB Licenses | ::Standard development licenses | ::6 | ::Pending | |
| ::DB Licenses | ::Production licenses | ::4 CPU's | ::2 Pending; ::2 Rejected | ::Testing group will use development DB server and do load testing in off hours |
| ::Software component | ::GIS Library w/ source code | ::1 | ::Pending | ::One time fee, approx. $10,000 |
| ::Software component | ::Encryption library | ::1 | ::Pending | ::Revenue sharing at 2% |
#### Possible Status Values
- Pending: request is awaiting management decision
- Assigned: task has been assigned to a person in the issue tracker
- Allocated: capital request approved by management, but resource has
not arrived
- Satisfied: request is satisfied, resource has arrived
- Rejected: requested resource will not be allocated, plan must be
adjusted to work without this resource
### Resource Needs Checklist
The goal of this checklist is to help expose resource needs that might
otherwise be missed. It does not help with the actual estimated number
of hours needed. Those estimates should be based on the project plan.
*TODO: Answer the questions below. If multiple sample answers are
provided, [chip away](Glossary-Standard-Terms#chipping-away) the ones that do
not apply. Edit any provided answers as needed. Use this exercise to
help you fill in the tables above.*
#### Does this project need more than a few days work?
:: Yes. A project manager role is needed to oversee the project.
:: No. The developers can manage their own work.
#### Are the requirements already completely defined and validated?
:: Yes. No additional time is needed for requirements.
:: No. Effort is needed for requirements.
#### What aspects of the system need to be designed?
:: General design. Group developer effort needed.
:: User interface. UI designer and domain experts effort needed.
:: Database design. Developer and DBA effort needed.
:: Security design. Developer and topic expert effort needed.
:: Other design. Developer, domain, and/or topic expert effort needed.
#### Does the project plan include any new development?
:: Yes. Development resources are needed.
:: No. No developers are needed
#### Does the project plan include complex configuration of existing components?
:: Yes. Component expert needed. Also need time to coordinate with
development and operations teams.
:: No. No component experts are needed
#### Does the development team have knowledge of all tools, components, and technologies to be used?
:: Yes. No training time needed.
:: No. Effort needed for training. Need training materials, courses, or
time with experts or mentors. List specific training
needs individually.
#### Is the entire development team have an agreed upon software development methodology?
:: Yes. No effort needed for defining a methodology.
:: Yes. But, effort is needed to refine the methodology to the project
at hand.
:: No. Effort needed to define and document a methodology and train all
team members. Additional effort needed for refinements throughout
the project.
#### Does the project plan include end-user documentation?
:: Yes. Technical writing resources must be allocated.
:: No.
#### What is the complexity of the internal documentation?
:: Significant. Technical writing resources must be allocated.
:: Average. Developers can produce technical documents as they go.
#### Will the technical support, training, operations, or services groups deal with the product of this project?
:: Yes. Effort must be allocated to train the staff in those groups.
:: No, but other developers will need training to reuse this component.
:: No. Effort put into producing good technical documentation should
be enough.
#### Will the product of this project be sold to customers, directly or indirectly?
:: Yes. The full SDM must be followed, including effort by a change
control board and release engineering.
:: No, it is for internal use only but it will be used repeatedly to
help build a shipping product. Release engineering and CCB effort is
still needed.
:: No, it is for internal use only and will only be used once. Release
engineering and CCB effort not needed.
#### Does the QA plan call for the running of automated unit tests?
:: Yes. Development effort will be needed to implement unit tests.
:: No. Additional QA effort will be needed for manual testing.
#### Does the QA plan call for more than the running of automated unit tests?
:: Yes. QA effort will be needed.
:: No. Unit tests will be enough for this component, full QA can be
done on products that use this component.
#### How many development workstations will be needed?
:: 1 per developer.
:: 1 per developer, plus extra for...
#### What development servers are needed?
:: None.
:: One for the whole team.
:: One for the one aspect of development, another for another aspect.
:: One for the one branch of development, another for another branch.
#### What database servers are needed?
:: None. No database is being used.
:: None. Database is integrated into product and does not require a
separate server.
:: One for the whole team.
:: One for the developers, one for QA.
:: One for one branch of development, another for another branch.
:: One for the developers, one for QA, one for load testing.
:: One for each developer or tester, plus one for load testing.
#### What machines are needed for automated testing?
:: None. Automated testing will not be done.
:: None. Automated testing will be done on workstations.
:: One for all nightly automated tests.
:: One for one aspect of nightly automated tests, another for
another aspect.
:: One for one branch of development, another for another branch.
#### What machines are needed for load testing?
:: None. Load testing will not be done.
:: None. Load testing will be done on workstations.
:: One machine will do all load testing.
:: Several machines needed to act as clients and servers.
:: One cluster of load testing machines for each branch of development.
#### What development tools must be licensed for this project?
:: None. Everything is implemented by us.
:: None. All development tools are open source.
:: Some tools: IDE, database, testing tools. These tools have already
been purchased, installed, and configured.
:: Some tools: IDE, database, testing tools. Budget must be allocated
to purchase these tools. Effort must be allocated to research and
select tools for purchase, install, and configure them.
#### What software components must be licensed for this project?
:: None. Everything is implemented by us.
:: None. All reused components are open source.
:: Some components: database, server software, libraries. These
components have already been selected, purchased, installed,
and configured.
:: Some components: database, server software, libraries. Effort must
be allocated to research, select, install and configure
these components. Budget must be allocated to purchase them.
#### Are any of the personnel assignments of capital allocations conditional?
:: Yes. All such conditions are written in the comments column above.
We have a contingency plan that will still achieve (an
acceptable subset) of the project goals.
:: No. Management has set aside these resources as promised, and the
needs of this project will take priority over any other project that
is likely to need the same resources.
#### Have these resource assignments been communicated to the people being assigned and their managers?
:: Yes, everyone understands. Feedback is welcome.
:: No, this is a risk that is noted in the [Risk
Management](Project-Plan#Risk-Management) section.

21
ProductDocumentation/Review-Meeting-Checklists.md Normal file
View File

@ -0,0 +1,21 @@
# Review Meeting Checklists
---
## Checklists for Types of Artifacts
- ::[Checklists for peer reviews](http://processimpact.com/pr_goodies.shtml)
by Karl E. Wiegers
- ::[Checklists for UML design](http://www.modelingstyle.info/)
by Scott W. Ambler
## Style Guides
- ::[Sun's java style guide](http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html)
- ::[Sun's javadoc guide](http://java.sun.com/j2se/javadoc/writingdoccomments/)
- ::[PHPBuilder.com's PHP style guide](http://www.phpbuilder.com/columns/tim20010101.php3)
- ::[Alltasks.net PHP style guide](http://alltasks.net/code/php_coding_standard.html)
- ::[C\# style guide](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions)
- ::[More C++ style guides](http://directory.google.com/Top/Computers/Programming/Languages/C%2B%2B/Style/)
- ::[More Java style guides](http://directory.google.com/Top/Computers/Programming/Languages/Java/Coding_Standards/)
- ::[Python PEP 8 style guide](https://www.python.org/dev/peps/pep-0008/)

67
ProductDocumentation/Review-Meeting-Notes.md Normal file
View File

@ -0,0 +1,67 @@
##### Project
::[PROJECT-NAME](Home)
##### Release Number
::X.Y.Z
##### Location of Meeting
::LOCATION, BUILDING, ROOM
##### Date and Time of Meeting
::YEAR/MONTH/DAY HH:MM
##### Attendees
- ::PERSON-NAME
- ::PERSON-NAME
- ::PERSON-NAME
- ::PERSON-NAME
##### Related Documents
- [QA Plan](QA-Plan) > Review Meeting Notes
- [Review Meeting Checklists](Review-Meeting-Checklists)
---
### Documents and Code Reviewed at this Meeting
- ::[Feature list section of requirements](#)
- ::[Multi-user section of requirements](#)
- ::[Hello.java](/source/browse/PROJECT-NAME/src/Hello.java)
- ::[HelloStream.java](/source/browse/PROJECT-NAME/src/HelloStream.java)
- ::[HelloPanel.java](/source/browse/PROJECT-NAME/src/HelloPanel.java)
### Meeting Minutes
*TODO: Fill in the information above and write a brief summary of what
happened at the meeting. The text below is just a sample.*
::We started on time with 3 members and the other team members arrived
shortly thereafter.
::In the first hour of the review meeting, we went over issues that the
team had entered individually. Most of the issues raised questions about
the error handling capability of Hello.java, but there were also issues
about multi-user robustness requirements and UI.
::In the second hour, we read through all of the methods of
HelloStream.java. All team members agreed that they understood each
method and thought is was correct before we moved on to the next method.
We raised issues of consistency between the constructors in that class
and other classes. The checklist was helpful in identifying the fact
that we needed to implement hash() and equals(). All raised issues were
entered into the issue tracker and marked with the word "review".
::Although, some issues were found, we do not feel that Hello.java and
HelloStream.java need to be inspected again. HelloPanel was not
inspected, it still needs review.
### Action Items
::All defects and tasks identified in this review are being tracked in the
issue tracker.

176
ProductDocumentation/Risks.md Normal file
View File

@ -0,0 +1,176 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Project plan](Project-Plan)
- [Software development methodology](SDM)
##### References:
- [Risk Management during Requirements](http://www.systemsguild.com/pdfs/s5req.lo%201.pdf) by Tom DeMarco and Tim Lister
- [Taxonomy-Based Risk Identification](http://www.sei.cmu.edu/pub/documents/93.reports/pdf/tr06.93.pdf) by Carr, Konda, Monarch, Ulrich, and Walker (SEI)
---
**Process impact:** This document records the major project risks, and
plans to control them. For each risk the plan should include:
- Mitigation plan
- Measures you will carry out now, to reduce the likelihood and/or
impact of the risk. Alternatively, you can decide to accept
the risk.
- Indicator
- A sign you will monitor to determine if the risk is beginning to
have an impact on the project.
- Contingency plan
- What you will do if the risk does arise. You can specify some
general contingency plans. In this case you only need to give a
contingency plan if you have a special one for the particular risk.
The severity of a risk is its likelihood multiplied by its impact. Risks
are classified as minor if they have low likelihood, negligible impact,
or medium likelihood and marginal impact.
*TODO: You should update these lists regularly. They should be reviewed
by customers and developers from time to time.*
### General contingency plans
#### Catastrophic risks
::If a catastrophic risk occurs we will make an honest reassessment of
the viability of the project and involve the relevant
project stakeholders.
::If a catastrophic risk occurs we will cancel the project. We will
take away our lessons learned and any valuable project bi-products.
::We do not recognize any catastrophic risks. If one occurs we will
pretend everything is fine and hope that none of the
stakeholders notice.
#### Risks that consume development resources.
::The project has a fixed deadline. The requirements are prioritized.
If we lose time, we will reduce project scope.
::The features specified are all essential If we lose time, we will
delay delivery.
::If we lose time, we will make time estimates for the remaining
features, and meet with the customers to reconsider scope and
delivery date.
#### ::OTHER RISK TYPE
::OTHER CONTINGENCY PLAN
### Major risks
| Name | Description | Likelihood | Impact | Plan | Status | Owner |
|-----------------|---------------------------------------------------------------------------------------------------------------------------------|------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|-------------------|
| ::Requirements | Requirements are only partly known at project start. Customers may not allocate sufficient resources to exploring requirements. | Medium | Critical to Catastrophic | Requirements will be detailed first for the top priority goals. Indicator: Track the rate at which requirements are discovered. Contingency: request more customer effort. | Amber | Requirements Lead |
| ::Goals | Stakeholders goals may conflict. | Medium | Critical | Keep an explicit list of stakeholders goals. The project manager will report progress to each declared goal. | Green | Customers |
| ::Communication | Communication problems in development team. They are dispersed among several sites, and have not worked together before. | Medium | Critical | Use these [tools](SDM#communication) to help communication. The main indicator of miscommunication will be software defects detected by our [QA activity](qa-plan). | Green | QA lead |
| ::Acceptance | Customer may accept delivery of the system although it does not really meet their goals. | Medium | Critical | Customers are asked to declare acceptance criteria as each release is planned. | Green | Customers |
| ::Scope | The total features requested may be beyond what the development team can deliver in the time available. | High | Marginal | Assign levels of important to the use cases. Make the first review of project scope after 12 months. | Green | Customers |
### Minor risks
*TODO: Review this list regularly, to decide whether the likelihood or
impact of a risk has increased to make it a "major" risk.*
| Name | Description | Likelihood | Impact | Mitigation Strategy | Status | Owner |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|-----------------|
| ::Estimate | The development team might not be able to estimate the work time, preventing customers from deciding priorities effectively. | Medium | Marginal | The development team will gain experience in estimating the work, and deliver the first estimates after 12 months. We will compare estimated work to actual work. | Green | Project Manager |
| ::Retention | Some developers may leave the project before it is finished. | Medium | Marginal | Employing locations should provide support for continuing professional development. The project manager will discuss career goals with each developer, and try to assign tasks appropriately. | Green | Project Manager |
| ::Correctness | The system as delivered may have low take-up because of a lack of confidence in its correctness. | Low | Catastrophic | State of the art [QA activity](QA-Plan). Contingency: stop development of new facilities until the quality of the existing code is assured. | Green | QA Lead |
| ::Usability | The system as delivered may have low take-up because of poor usability. | Low | Critical | We will have a UI style guide. Most of the development of the front end will be in close contact with customers. We will review usability later in the project. | Green | UI design lead |
| ::Desire | The stated requirements might not match the customers' desires and ambitions for the system. | Low | Critical | Incremental delivery of versions will provide experience of using the system, which will help the customers to identify the real requirements. Indicator: a developer saying "I think they mean ...", a customer saying "They know what I mean". Contingency: request customer review of requirements. | Green | Customers |
| ::Changes | After requirements have been documented and agreed, development activities begin to based on them, first design then implementation. If the requirements change later then effort is wasted. | Low | Critical | A change control procedure is required, so changes are only made when the cost is worthwhile. Indicator: compare cost of change to new development. Contingency: request customer review of requirements. | Green | Project Manager |
| ::Process | Some developers may not cooperate in common standards and processes. | Low | Critical | QA to check conformance, then discussions in development team meetings to change the standard or the actual practice as appropriate. | Green | QA Lead |
| ::Maintainability | The system as delivered might be hard to maintain. | Low | Marginal | We will review the code for maintainability. | Green | Lead Developer |
| ::RISK-NAME | ONE-TO-THREE-SENTENCES | Low or Medium or High | Negligible or Marginal or Critical or Catastrophic | ONE-TO-THREE-SENTENCES | Red or Amber or Green | PERSON-NAME |
#### Possible risk status values
##### Red
Active & impacting project
##### Amber
Active but contained without impact to scope or delivery time.
##### Green
Not yet active
### Risk Checklist
#### Do the plans provide an indicator to detect each of the risks becoming active?
::Yes, if all activities are carried out as planned, we will know if any
of the risks is becoming troublesome.
::No, some risks could creep up on us.
#### Are the right "risk owners" assigned to monitor the risks?
::Yes, for each risk the assigned owner can detect the indicator, can
launch the contingency plan, and is the person who will suffer by
the risk.
::No, in some cases the assigned owner may not notice or care, or does
not have sufficient authority.
#### Does each risk have a mitigation strategy, or is the risk acceptable?
::Yes, we have plans to control each risk.
::Yes, we have plans to control some risks, and have accepted others.
::No, this plan leaves open several risks.
#### Does each risk have a contingency plan?
::Yes, most risks cost development time and the general plan applies,
and for each of the others there is a contingency plan above.
::No, there are some risks we still have to plan for.
#### Has this Risk Control Plan been communicated to the development team and other stakeholders?
::Yes, this document is being posted to the project website. It will
also be discussed at an early team meeting, and discussed with the
customers before the commit to the project. Comments are welcome.
::No, our culture does not allow discussion of risks.
#### Is there a procedure in place for identifying new risks and reviewing the existing ones?
::TBD
#### In the light of these risks, is the project worth carrying out?
::Yes, it is a low risk project
::No, other projects can deliver as much value at lower risk.
::Yes. It is an unusually risky project by commercial standards, but
we believe we have adequate plans here, considering the value that
the project could deliver.
#### Is there an anonymous reporting channel, to allow developers to communicate concerns to senior management?
::Yes
RISKNAME
RISKNAME and strength of character of
RISKNAME
RISKNAME

5
ProductDocumentation/SDM.md Normal file
View File

@ -0,0 +1,5 @@
*TODO: This template is not done yet. Feel free to contribute your ideas.*
A Software Development Methodology is always specific to a given
company, but the outline of that document could be reused, as could some
sections on common practices such as version control procedures.

256
ProductDocumentation/SRS.md Normal file
View File

@ -0,0 +1,256 @@
##### Project
::PROJECT-NAME
##### Internal Release Number
::X.Y.Z
##### Attached worksheets:
- SRS > [Use case suite](Use-Case-Suite)
- SRS > [Feature set](Feature-Set)
##### Related Documents
- [Project proposal](Proposal) > [User needs](User-Needs)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
- [Glossary](Glossary)
---
**Process impact:** The SRS precisely defines the software product that
will be built. Decisions made in writing the SRS are based on
information in the [project proposal](Proposal) and [user
needs](User-Needs) documents. The SRS sets requirements that must
be satisfied by the [system design](Design). The SRS is verified
and validated by activities outlined in the [QA plan](QA-Plan).
### Introduction
*TODO: Provide a brief overview of this release of the product. You can
copy text from the project proposal, paste it here, and shorten it.*
::PARAGRAPH
::PARAGRAPH
For more information, see the project [proposal](Proposal).
### Use Cases
::ONE PARAGRAPH OVERVIEW
Details:
- Actors are described in the [user needs](User-Needs) document.
- The [use case suite](Use-Case-Suite) lists all use cases in an
organized way.
### Functional Requirements
::ONE PARAGRAPH OVERVIEW
Details:
- The [feature set](Feature-Set) lists all features in an
organized way.
### Non-Functional Requirements
*TODO: Describe the non-functional requirements for this release. Some
examples are provided below.*
#### What are the usability requirements?
::Our main criteria for making the system usable is the difficulty of
performing each high-frequency use case. Difficulty depends on the
number of steps, the knowledge that the user must have at each step,
the decisions that the user must make at each step, and the
mechanics of each step (e.g., typing a book title exactly is hard,
clicking on a title in a list is easy).
::The user interface should be as familiar as possible to users who
have used other web applications and Windows desktop applications.
E.g., we will follow the UI guidelines for naming menus, buttons,
and dialog boxes whenever possible.
::PARAGRAPH
Details:
- ::Government customers will demand [section508
compliance](http://www.section508.gov/)
- ::Support learnability with principles of [Instructive
Interaction](http://www.foruse.com/articles/instructive.htm)
- ::The customer wants extensive on-line help, but is not demanding
a printed manual.
#### What are the reliability and up-time requirements?
::PARAGRAPH
::PARAGRAPH
Details:
- ::DETAIL
- ::DETAIL
- ::DETAIL
#### What are the safety requirements?
::PARAGRAPH
::PARAGRAPH
Details:
- ::DETAIL
- ::DETAIL
- ::DETAIL
#### What are the security requirements?
::Access will be controlled with usernames and passwords.
::Only administrator users will have access to administrative
functions, average users will not.
Details:
- ::Passwords must be 4-14 characters long
- ::We will not use encrypted communications (SSL) for this website
- ::DETAIL
#### What are the performance and scalability requirements requirements?
::PARAGRAPH
::PARAGRAPH
Details:
- ::DETAIL
- ::DETAIL
- ::DETAIL
#### What are the maintainability and upgradability requirements?
::Maintainability is our ability to make changes to the product
over time. We need strong maintainability in order to retain our
early customers. We will address this by anticipating several types
of change, and by carefully documenting our design
and implementation.
::Upgradability is our ability to cost-effectively deploy new versions
of the product to customers with minimal downtime or disruption. A
key feature supporting this goal is automatic download of patches
and upgrade of the end-user's machine. Also, we shall use data file
formats that include enough meta-data to allow us to reliably
transform existing customer data during an upgrade.
Details:
- ::DETAIL
- ::DETAIL
- ::DETAIL
#### What are the supportability and operability requirements?
::Supportability is our ability to provide cost effective
technical support. Our goal is to limit our support costs to only 5%
of annual licensing fees. The product's automatic upgrade feature
will help us easily deploy defect fixes to end-users. The user guide
and product website will include a troubleshooting guide and
checklist of information to have at hand before contacting
technical support.
::Operability is our ability to host and operate the software as an
ASP (Application Service Provider). The product features should help
us achieve our goal of 99.9% uptime (at most 43 minutes downtime
each month). Key features supporting that are the ability to do hot
data backups, and application monitoring.
Details:
- ::DETAIL
- ::DETAIL
- ::DETAIL
#### What are the business life-cycle requirements?
::The business life-cycle of a product includes everything that
happens to that product over a period of several years, from initial
purchase decision, through important but infrequent use cases, until
product retirement. Key life-cycle requirements are listed below.
Details:
- ::Customers must be able to manage the number of licenses that
they have and make informed decisions to purchase more licenses
when needed
- ::The product shall support daily operations and our year-end
audit
- ::The customer data shall be stored in a format that is still
accessible even after the application has been retired
### Environmental Requirements
*TODO: Describe the environmental requirements for this release.
Environmental requirements describe the larger system of hardware,
software, and data that this product must work within. Some examples are
provided below.*
#### What are the system hardware requirements?
::PARAGRAPH
::PARAGRAPH
Details:
- ::DETAIL
- ::DETAIL
- ::DETAIL
#### What are the system software requirements?
::PARAGRAPH
::PARAGRAPH
Details:
- ::DETAIL
- ::DETAIL
- ::DETAIL
#### What application program interfaces ([APIs](Glossary-Standard-Terms#api_application_programming_interface)) must be provided?
::PARAGRAPH
::PARAGRAPH
Details:
- ::We must implement this [standard API](LINK-TO-STANDARD).
- ::DETAIL
- ::DETAIL
#### What are the data import and export requirements?
::PARAGRAPH
::PARAGRAPH
Details:
- ::The system will store all data in a standard SQL database, where
it can be accessed by other programs.
- ::The system will store all data in an XML file, using a
[standard DTD](LINK-TO-STANDARD).
- ::The system will read and write valid .XYZ files used by
OTHER APPLICATION
- ::DETAIL

162
ProductDocumentation/Status-Report.md Normal file
View File

@ -0,0 +1,162 @@
*TODO: Copy this file for each status report. Fill in the information
below. Email a notification to stakeholders when this report is made
available.*
*TODO: Edit the rows in the following table. In some rows, multiple
examples are given, you should select/edit only one.*
##### Project
::[PROJECT-NAME](Home)
##### Status Report Date
::YEAR/MONTH/DAY
##### Next Internal Release Number
::X.Y.Z
##### Release Date
- ::Original estimate: YEAR/MONTH/DAY
- ::Current estimate: YEAR/MONTH/DAY
- ::Change Since Last Report: No change
- ::Change Since Last Report: Slipped 2 days
- ::Change Since Last Report: Saved 4 days
##### Open Issues (needing development):
- ::[17 defects](ISSUE-TRACKER-QUERY)
- ::[8 enhancements](#)
##### Resolved Issues (pending verification):
- ::[0 defects](#)
- ::[2 enhancements](#)
##### Closed Issues:
- ::[34 defects](#)
- ::[3 enhancements](#)
##### Resources used this period:
- ::PERSON-NAME: 18 hours.
- ::PERSON-NAME: 15 hours.
- ::PERSON-NAME: 10 hours.
- ::PERSON-NAME: 12 hours.
##### Status Summary:
- ::Project completed. This is the final status report.
- ::Low risk. Project on track.
- ::Medium risk. Problems are being dealt with.
- ::High risk. Advice from management and stakeholders needed.
- ::Project canceled. This is the final status report.
##### Related Documents
- [Project plan](Project-Plan) > [Resource needs](Resource-Needs)
- [QA plan](QA-Plan)
- [Glossary](Glossary)
---
**Process impact:** This helps keep stakeholders informed of project
status so that they may correctly set expectations. Reasoned
explanations of slight changes in schedule are much better than major
unexplained slips.
### Detailed Status
TODO: Provide 1-4 paragraphs describing what has happened on this
project. The text below is just an example, replace it with your own
words.
::This week we focused on...
::Two major problems have been uncovered...
::We are approximately 30% of the way through the project plan, and running about 2 days ahead of schedule...
::The reason for the change in estimated release date is...
::To stay on schedule, we have slipped enhancements [issue92](ISSUE-TRACKER-URL),
[issue 101](ISSUE-TRACKER-URL), and [issue 129](ISSUE-TRACKER-URL) to a later
release. These issues were selected because ...
### Risk Management
*TODO: List 3-10 of the top project risks that are still outstanding.
This list may be an **updated** copy from [project plan](Project-Plan.html#Risk-Management)
or a previous status report.*
- ::We could face major difficulties with the technology chosen for
this project. HOW TO AVOID/MITIGATE?
- ::We could have low quality that demands significant rework. HOW TO
AVOID/MITIGATE?
- ::We could incorrectly assess our progress until it is too late
to react. HOW TO AVOID/MITIGATE?
- ::There may be a mis-alignment of stakeholder goals or expectations.
HOW TO AVOID/MITIGATE?
### Upcoming Activity
*TODO: Provide a few bullets describing what you will do between now and
the next status report. The text below is just an example, replace it
with your own words. Link to open issues in the issue tracker whenever
possible.*
- ::Fix [issue 130](ISSUE-TRACKER-URL)
- ::Fix [issue 133](ISSUE-TRACKER-URL)
- ::Verify [issue 102](ISSUE-TRACKER-URL), [issue 103](ISSUE-TRACKER-URL),
[issue 107](ISSUE-TRACKER-URL), and [issue 109](ISSUE-TRACKER-URL)
- ::Conduct regular team meeting: Tuesday, 1 hour
- ::Conduct review meeting: Wednesday, 2 hours
- ::Make major progress on COMPONENT
- ::Work through next release checklist
- ::Continue functional testing
- ::Revise our integration procedure
- ::Release version X.Y.Z
### Tracking to Plan
*TODO: Copy the Work Breakdown Structure from the [project plan](Project-Plan) and paste it here.
Add a new column for actual effort spent so far by all team members.*
| Step | Description | Planned Hours | Spent To-Date |
|------------|----------------------------------------------------------------------|---------------|---------------|
| ::1. | ::Preparation | | |
| ::1.1. | ::Developer training | ::30h | ::0h |
| ::2. | ::Inception | | |
| ::2.1. | ::Requirements gathering | ::30h | ::0h |
| ::2.2. | ::Requirements specification | ::20h | ::0h |
| ::2.3. | ::Requirements validation | ::10h | ::0h |
| ::3. | ::Elaboration | | |
| ::3.1. | ::High-level design | ::5h |::0h |
| ::3.2. | ::Low-level design (break down by component) | | |
| ::3.2.A. | ::Object design | ::10h | ::0h |
| ::3.2.B. | ::User interface design | ::10h | ::0h |
| ::3.2.C. | ::Database design | ::3h | ::0h |
| ::3.3. | ::Design review and evaluation | ::5h | ::0h |
| ::4. | ::Construction | | |
| ::4.1.A. | ::System implementation | | |
| ::4.1.A.1. | ::Implement Component 1 | ::25h | ::0h |
| ::4.1.A.2. | ::Implement Component 2 | ::25h | ::0h |
| ::4.1.A.3. | ::Implement Component 3 | ::25h | ::0h |
| ::4.1.A.4. | ::Implement Component 4 | ::25h | ::0h |
| ::4.1.A.5. | ::Integrate Components (mostly done during component implementation) | ::5h | ::0h |
| ::4.1.B. | ::Technical documentation (break down by component) | ::10h | ::0h |
| ::4.1.C. | ::User documentation (break down by component) | ::10h | ::0h |
| ::4.1.D. | ::Testing | | |
| ::4.1.D.1. | ::Test planning | ::10h | ::0h |
| ::4.1.D.2. | ::Test code implementation (break down by component) | ::30h | ::0h |
| ::4.1.D.3. | ::Test execution | ::10h | ::0h |
| ::4.2. | ::Implementation review and evaluation | ::15h | ::0h |
| ::5. | ::Transition | | |
| ::5.A. | ::Release packaging | ::3h | ::0h |
| 5.B. | ::Documentation for other groups | ::3h | ::0h |
| ::6. | ::Reflection | | |
| ::6.1. | ::Postmortem report | ::10h | ::0h |
| | Total | ::329 hours | |

224
ProductDocumentation/Summary.md Normal file
View File

@ -0,0 +1,224 @@
### Mission and Scope
*TODO: Answer these questions in your own words. This is condensed
from the project [Home](Home).*
#### What problem does this project address?
::2-4 SENTENCE PROBLEM
#### What is the goal of this project?
::2-4 SENTENCE GOAL
#### What is the scope of this project
::2-4 SENTENCE SCOPE
### Status
*TODO: Briefly describe the status of this project. E.g., what phase are you in? And, what is your next major milestone? Detailed project status is written in the status reports, not here.*
::We have completed our second beta release and are currently working on
adding more of the functionality described in our product
[specification](SRS) and fixing defects.
::The next major milestone is a third beta release with nearly complete
functionality and a wider set of testers.
#### Status reports
- ::[Status report 1](status-report.html)
- ::[Status report 2](status-report2.html)
- ::Etc.
### Resources and schedule
*TODO: Briefly describe the project resources and schedule. This is
condensed from the [project plan](Project-Plan), [resource needs](Resource-Needs),
and [legal issues](legal.html) documents.*
#### What are the deadlines for this project?
- ::DATE: MILESTONE
- ::DATE: MILESTONE
- ::DATE: MILESTONE
- ::DATE: RELEASE-NUMBER
#### Who is working on this project?
- ::100% PERSON-NAME
- ::100% PERSON-NAME
- ::75% PERSON-NAME
- ::33% PERSON-NAME
#### What capital resources are allocated to this project?
- ::HARDWARE
- ::SOFTWARE LICENSE
- ::FACILITIES
#### What are the main legal concerns for this project?
- ::Intellectual property: DESCRIPTION
- ::Privacy and security: DESCRIPTION
- ::Potential harm: DESCRIPTION
### Requirements
*TODO: Briefly describe the most important system requirements. This is
condensed from the [user needs](User-Needs),
[interview notes](interview-notes.html), [SRS](SRS),
[use case suite](Use-Case-Suite),
and [feature set](Feature-Set) documents.*
#### Who are the project stakeholders?
- ::PROJECT CHAMPION / EXECUTIVE SPONSOR
- ::DEPARTMENTS WITHIN YOUR COMPANY
- ::CORPORATE PARTNERS
- ::KEY CUSTOMERS
#### What user needs have you gathered?
- ::[User stories](LINK-TO-USER-STORIES)
- ::[Interview notes](LINK-TO-INTERVIEW-NOTES)
#### What are the requirements specifications?
- ::[Use cases](LINK-TO-USE-CASES)
- ::[Feature specifications](LINK-TO-FEATURE-SPECS)
- ::[Environmental requirements](LINK-TO-ENV-REQ)
- ::[Other requirements](LINK-TO-OTHER-REQ)
### Design
*TODO: Briefly describe the most important aspects of the design. This is
condensed from the [design](Design) template and associated
worksheets.*
#### What are your ranked design goals?
1. ::Correctness
- ::This design correctly matches the
given requirements.
2. ::Feasibility
- ::This design can be implemented and tested with the
planned amount of time and effort.
3. ::Understandability
- ::Developers can understand this design and
correctly implement it.
4. ::Implementation phase guidance
- ::This design divides the
implementation into components or aspects that can correspond to
reasonable implementation tasks.
5. ::Modularity
- ::Concerns are clearly separated so that the impact of
most design changes would be limited to only one or a
few modules.
6. ::Extensibility
- ::New features can be easily added later.
7. ::Testability
- ::It is easy to test components of this design
independently, and information is available to help
diagnose defects.
8. ::Efficiency
- ::The design enables the system to perform functions
with an acceptable amount of time, storage space, bandwidth, and
other resources.
#### Where are your design documents?
- ::[UML class diagram](LINK-TO-CLASS-DIAGRAM)
- ::[UML class diagram](LINK-TO-CLASS-DIAGRAM)
- ::[UML state diagram](LINK-TO-STATE-DIAGRAM)
- ::[UML sequence diagram](LINK-TO-SEQUENCE-DIAGRAM)
- ::[UML deployment diagram](LINK-TO-DEPLOYMENT-DIAGRAM)
- ::[Other design](LINK-TO-OTHER-DESIGN)
### Quality Assurance
*TODO: Briefly describe your quality goals and how you will achieve them.
This is condensed from the [QA plan](QA-Plan), [test
suite](test-suite), and [test cases](test-cases.html) documents.*
#### What are your ranked quality goals?
1. ::Correctness
2. ::Robustness
3. ::Accuracy
4. ::Compatibility
5. ::Usability
6. ::Security
7. ::Reliability
8. ::Scalability
9. ::Operability
10. ::Maintainability
#### What QA activities will you use?
- ::Preconditions and assertions
- ::Buddy reviews
- ::Review meetings
- ::Unit testing
- ::System testing
#### Where are the test cases?
- ::[Test case](LINK-TO-TEST-CASE)
- ::[Test case](LINK-TO-TEST-CASE)
- ::[Test case](LINK-TO-TEST-CASE)
- ::[Test case](LINK-TO-TEST-CASE)
### Packaging, Delivery, and Deployment
Where is the release checklist or sign-off document?
::[Release checklist](LINK-TO-RELEASE-CHECKLIST)
#### How is the product packaged and deployed?
- ::Packaging: DESCRIPTION
- ::Deployment: DESCRIPTION
- ::[Release notes](LINK-TO-RELEASE-NOTES)
#### How is the product installed?
- ::System requirements: DESCRIPTION
- ::STEP
- ::STEP
- ::STEP
### User Support
Where is the user documentation?
- ::[User guide](LINK-TO-USER-GUIDE)
- ::[User FAQ](LINK-TO-FAQ)
#### How can users get technical support or report problems?
- ::Support: DESCRIPTION
- ::Issue tracking: DESCRIPTION
### Glossary
*TODO: Define any technical terms that you use above, if a new member of
the team would not already know them. This is condensed from the
[glossary](Glossary) documents.*
##### ::TECHNICAL TERM 1
::DEFINITION
##### ::TECHNICAL TERM 2
::DEFINITION
##### ::TECHNICAL TERM 3
::DEFINITION
##### ::TECHNICAL TERM 4
::DEFINITION

139
ProductDocumentation/Target-and-Benefits.md Normal file
View File

@ -0,0 +1,139 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [Proposal](Proposal) > Target Audience and Benefits
- [Project proposal](Proposal) > [User needs](User-Needs)
- [Glossary](Glossary)
---
**Process impact:** 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.
### Target Audience
*TODO: Fill in the information above and below. Provided answers are only
examples. Delete them and answer in your own words.*
#### What market segment is this product in?
::Console video games. Specifically, first-person shooters.
::Anti-virus software for cellular phones.
::Open source development tools for SQL database design.
#### What is the target market for this product? Include specific defining characteristics.
::Experienced console game players age 13-35 who enjoy first-person
shooter games with detailed character animation models and
cinematic segments.
::Cellular phone users who frequently download ring-tones, video
games, and other content to high-end phones and who are concerned
about the potential for viruses.
#### What is the size of the total available market? Cite references for facts.
::10,000 users \[[magazine article](#)\].
::$10M, growing annually at 4% \[[industry analyst](#)\].
#### What are some other customer options or leading products that address the same needs?
- ::[Competitor 1](#)
- ::[Competitor 2](#)
- ::[Do-it-yourself solutions](#)
#### Are there any known customers for this product?
- ::[MegaCorp, corporate I.T. department](#)
- ::[Worldwide Global Corporation](#)
- ::Our own in-house application software developers and server
operations team
- ::Our own marketing, sales, and customer support departments
### Benefits to Customers
*TODO: List high-level benefits that this product will provide. For each,
identify the type of customer or user that will benefit. Each benefit
should be in real-world terms, not involving just this product itself.
You may want to highlight benefits that are not offered by competing
products. Benefits to the development organization should be listed in
[Risks and Rewards](Project-Plan#risk-management).*
*TIP: If you can rank benefits by value, use numbered lists (the HTML
&lt;ol> tag), otherwise use bullet lists (the HTML &lt;ul> tag).*
- ::Increases play-value
- ::Many players enjoy games more when they play as a team.
- ::Clans can greatly extend the time that a player plays one game,
thus reducing the expense of buying new games.
- ::Improves customer population
1. ::Clan players often encourage their friends to play the same
game, which gives game vendors more revenue.
2. ::Clans help to organize the customer population and create
channels of communication so that vendor information (e.g.,
about future releases) spreads more quickly with less
advertising expense and delay.
3. ::Clans attract the more experienced players who can give better
feedback to game vendors.
- ::Reduces current costs
- ::Reduced staffing costs
- ::Reduced training costs
- ::Reduced maintenance costs
- ::Reduced infrastructure costs
- ::Makes current processes more efficient
- ::Avoids penalty clauses of current contracts
- ::Opens new business opportunities
- ::Opens new sales opportunities
- ::Improves sales success rate or size
- ::Opens partnership opportunities
- ::Triggers bonus clauses current contracts
- ::Satisfies stakeholders
- ::Satisfies shareholders
- ::Satisfies partners
- ::Satisfies management or executives
- ::Satisfies government regulation or corporate policy
- ::Improves morale
- ::Helps take advantage of changing marketplace
- ::Reduced inventory or need for advance planning
- ::Speeds time-to-market
- ::Optimizes supply chain
- ::Reduces fixed costs
- ::Type of benefit
1. ::Most valuable benefit
2. ::Benefit
3. ::Benefit
- ::Type of benefit
- ::Benefit
- ::Benefit
- ::Benefit
### Potential Downside
*TODO: Could anyone be harmed or put at a disadvantage because of your
system? List as above. Note, these are not risks to the success of your
implementation, assume that you build the system as specified on time.*
- ::Privacy
- ::When players opt into clans, they also opt into receiving
marketing information from game vendors. Usually this is a good
thing if the players are interested, but it can also
be annoying.
- ::Cheaters will be publicly named as cheaters and blocked from
game servers, thus they lose the ability to play/cheat.
- ::Type of downside
1. ::Worst downside
2. ::Downside
3. ::Downside

130
ProductDocumentation/Test-Case-Format.md Normal file
View File

@ -0,0 +1,130 @@
##### Related Documents
- [QA Plan](QA-Plan) > [Test Suite](Test-Suite) > Test Case Format
---
**Process impact:** This reference page documents the format of test
cases and gives tips on writing test cases. You can copy and paste the
sample test case into your test-cases file. This file itself should
not be edited to hold specific test cases.
This test case format is suitable for manual system test cases.
The test cases should be written in enough detail that they could be
given to a new team member who would be able to quickly start to carry
out the tests and find defects.
---
### unique-test-case-id: Test Case Title
**Purpose:**
::Short sentence or two about the aspect of the system is being tested. If this gets too long, break the test case up or put more information into the feature descriptions.
**Prerequisite:**
Assumptions that must be met before the test case can be run. E.g., &quot;logged in&quot;, &quot;guest login allowed&quot;, &quot;user test-user exists&quot;.
**Test Data:**
List of variables and their possible values used in the test case. You can list specific values or describe value ranges. The test case should be performed once for each *combination* of values. These values are written in set notation, one per line. E.g.:
- ::loginID = {Valid loginID, invalid loginID, valid email, invalid email, empty}
- ::password = {valid, invalid, empty}
**Steps:**
Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter userID
- ::enter password
- ::click login
- ::see the terms of use page
- ::click agree radio button at page bottom
- ::click submit button
- ::see PersonalPage
- ::verify that welcome message is correct username
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### Format of test steps
Each step can be written very tersely using the following keywords:
#### ::login \[as ROLE-OR-USER\]
::Log into the system with a given user or a user of the given type.
Usually only stated explicitly when the test case depends on the
permissions of a particular role or involves a workflow between
different users.
#### ::visit LOCATION
::Visit a page or screen. For web applications, LOCATION may be
a hyperlink. The location should be a well-known starting point
(e.g., the Login screen), drilling down to specific pages should be
part of the test.
#### ::enter FIELD-NAME \[as VALUE\] \[in SCREEN-LOCATION\]
::Fill in a named form field. VALUE can be a literal value or the name
of a variable defined in the "Test Data" section. The FIELD-NAME
itself can be a variable name when the UI field for that value is
clear from context, e.g., "enter password".
#### ::enter FIELDS
::Fill in all fields in a form when their values are clear from
context or when their specific values are not important in this
test case.
#### ::click "LINK-LABEL" \[in SCREEN-LOCATION\]
::Follow a labeled link or press a button. The screen location can be
a predefined panel name or English phrase. Predefined panel names
are based on GUI class names, master template names, or titles of
boxes on the page.
#### ::click BUTTON-NAME \[in SCREEN-LOCATION\]
::Press a named button. This step should always be followed by a "see"
step to check the results.
#### ::see SCREEN-OR-PAGE
::The tester should see the named GUI screen or web page. The general
correctness of the page should be testable based on the
feature description.
#### ::verify CONDITION
::The tester should see that the condition has been satisfied. This
type of step usually follows a "see" step at the end of the
test case.
#### ::verify CONTENT \[is VALUE\]
::The tester should see the named content on the current page, the
correct values should be clear from the test data, or
given explicitly. This type of step usually follows a "see" step at
the end of the test case.
#### ::perform TEST-CASE-NAME
::This is like a subroutine call. The tester should perform all the
steps of the named test case and then continue on to the next step
of this test case.
*Every test case must include a verify step at the end so that the
expected output is very clear. A test case can have multiple verify
steps in the middle or at the end. Having multiple verify steps can be
useful if you want a smaller number of long tests rather than a large
number of short tests.*

365
ProductDocumentation/Test-Cases.md Normal file
View File

@ -0,0 +1,365 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
[QA Plan](QA-Plan) > [Test Suite](Test-Suite) > Test Cases
[System test case format](Test-Case-Format)
::LINKS TO RELEVANT STANDARDS
::LINKS TO OTHER DOCUMENTS
---
### login-1: Normal User Login
**Purpose:**
::Test that users can log in with the proper username or
email address and their password.
**Prerequisite:**
::User is not already logged in.
::User test-user exists, and account is in good standing.
**Test Data:**
::usernameOrEmail = {test-user, bogus-user, test-user@nospam.com,
test@user@nospam.com, empty}
::password = {valid, invalid, empty}
**Steps:**
::Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter userID
- ::enter password
- ::click login
- ::see the terms of use page
- ::click agree radio button at page bottom
- ::click submit button
- ::see PersonalPage
- ::verify that welcome message is correct username
**Notes and Questions:**
- ::This assumes that user has not agreed to terms-of-use already.
- ::Does this work without browser cookies?
---
### login-2: Locked-out User Login
**Purpose:**
::Test that a user who has been locked out by a moderator, cannot
log in, They should see a messagaddede indicating that they were locked
out.
**Prerequisite:**
::User is not already logged in.
::User test-user2 exists, and has been locked out
**Test Data:**
::usernameOrEmail = {test-user2, test-user2@nospam.com}
::password = {valid}
**Steps:**
::Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter usernameOrEmail
- ::enter password
- ::click Login
- ::see LoginPage
- ::verify warning message is the locked-out message
**Notes and Questions:**
- ::Does this work without browser cookies?
---
### unique-test-case-id1: Test Case Title
**Purpose:**
::Short sentence or two about the aspect of the system is
being tested. If this gets too long, break the test case
up or put more information into the feature descriptions.
**Prerequisite:**
::Assumptions that must be met before the test case can be run.
E.g., &quot;logged in&quot;, &quot;guest login allowed&quot;,
&quot;user test-user exists&quot;.
**Test Data:**
::List of variables and their possible values used in the test case.
You can list specific values or describe value ranges. The test case
should be performed once for each *combination* of values. These
values are written in set notation, one per line. E.g.:
- loginID = {Valid loginID, invalid loginID, valid email, invalid
email, empty}
- password = {valid, invalid, empty}
**Steps:**
::Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter userID
- ::enter password
- ::click login
- ::see the terms of use page
- ::click agree radio button at page bottom
- ::click submit button
- ::see PersonalPage
- ::verify that welcome message is correct username
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### unique-test-case-id2: Test Case Title
**Purpose:**
::Short sentence or two about the aspect of the system is
being tested. If this gets too long, break the test case
up or put more information into the feature descriptions.
**Prerequisite:**
::Assumptions that must be met before the test case can be run.
E.g., &quot;logged in&quot;, &quot;guest login allowed&quot;,
&quot;user test-user exists&quot;.
**Test Data:**
::List of variables and their possible values used in the test case.
You can list specific values or describe value ranges. The test case
should be performed once for each *combination* of values. These
values are written in set notation, one per line. E.g.:
- ::loginID = {Valid loginID, invalid loginID, valid email, invalid
email, empty}
- ::password = {valid, invalid, empty}
**Steps:**
::Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter userID
- ::enter password
- ::click login
- ::see the terms of use page
- ::click agree radio button at page bottom
- ::click submit button
- ::see PersonalPage
- ::verify that welcome message is correct username
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### unique-test-case-id3: Test Case Title
**Purpose:**
::Short sentence or two about the aspect of the system is
being tested. If this gets too long, break the test case
up or put more information into the feature descriptions.
**Prerequisite:**
::Assumptions that must be met before the test case can be run.
E.g., &quot;logged in&quot;, &quot;guest login allowed&quot;,
&quot;user test-user exists&quot;.
**Test Data:**
::List of variables and their possible values used in the test case.
You can list specific values or describe value ranges. The test case
should be performed once for each *combination* of values. These
values are written in set notation, one per line. E.g.:
- ::loginID = {Valid loginID, invalid loginID, valid email, invalid
email, empty}
- ::password = {valid, invalid, empty}
**Steps:**
::Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter userID
- ::enter password
- ::click login
- ::see the terms of use page
- ::click agree radio button at page bottom
- ::click submit button
- ::see PersonalPage
- ::verify that welcome message is correct username
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### unique-test-case-id4: Test Case Title
**Purpose:**
::Short sentence or two about the aspect of the system is
being tested. If this gets too long, break the test case
up or put more information into the feature descriptions.
**Prerequisite:**
::Assumptions that must be met before the test case can be run.
E.g., &quot;logged in&quot;, &quot;guest login allowed&quot;,
&quot;user test-user exists&quot;.
**Test Data:**
::List of variables and their possible values used in the test case.
You can list specific values or describe value ranges. The test case
should be performed once for each *combination* of values. These
values are written in set notation, one per line. E.g.:
- ::loginID = {Valid loginID, invalid loginID, valid email, invalid
email, empty}
- ::password = {valid, invalid, empty}
**Steps:**
::Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter userID
- ::enter password
- ::click login
- ::see the terms of use page
- ::click agree radio button at page bottom
- ::click submit button
- ::see PersonalPage
- ::verify that welcome message is correct username
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### unique-test-case-id5: Test Case Title
**Purpose:**
::Short sentence or two about the aspect of the system is
being tested. If this gets too long, break the test case
up or put more information into the feature descriptions.
**Prerequisite:**
::Assumptions that must be met before the test case can be run.
E.g., &quot;logged in&quot;, &quot;guest login allowed&quot;,
&quot;user test-user exists&quot;.
**Test Data:**
::List of variables and their possible values used in the test case.
You can list specific values or describe value ranges. The test case
should be performed once for each *combination* of values. These
values are written in set notation, one per line. E.g.:
- ::loginID = {Valid loginID, invalid loginID, valid email, invalid
email, empty}
- ::password = {valid, invalid, empty}
**Steps:**
::Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter userID
- ::enter password
- ::click login
- ::see the terms of use page
- ::click agree radio button at page bottom
- ::click submit button
- ::see PersonalPage
- ::verify that welcome message is correct username
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### unique-test-case-id6: Test Case Title
**Purpose:**
::Short sentence or two about the aspect of the system is
being tested. If this gets too long, break the test case
up or put more information into the feature descriptions.
**Prerequisite:**
::Assumptions that must be met before the test case can be run.
E.g., &quot;logged in&quot;, &quot;guest login allowed&quot;,
&quot;user test-user exists&quot;.
**Test Data:**
::List of variables and their possible values used in the test case.
You can list specific values or describe value ranges. The test case
should be performed once for each *combination* of values. These
values are written in set notation, one per line. E.g.:
- ::loginID = {Valid loginID, invalid loginID, valid email, invalid
email, empty}
- ::password = {valid, invalid, empty}
**Steps:**
::Steps to carry out the test. See step formating rules below.
- ::visit LoginPage
- ::enter userID
- ::enter password
- ::click login
- ::see the terms of use page
- ::click agree radio button at page bottom
- ::click submit button
- ::see PersonalPage
- ::verify that welcome message is correct username
**Notes and Questions:**
- ::NOTE
- ::QUESTION

82
ProductDocumentation/Test-Run-Suite.md Normal file
View File

@ -0,0 +1,82 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [QA Plan](QA-Plan) > Test Run Suite
- [Test suite](Test-Suite)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
**Process impact:** 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.
*TODO:*
- *Review the [target audience](Target-and-Benefits),
[environmental requirements](SRS#environmental), and [possible
deployments](Design-Architecturel#deployment) to understand the
set of possible system configurations that could be tested.*
- *Use a table or list to describe that set of possible configurations.
Mark each possibility with Pending, N/A, or Waived.*
- *Track each test run with an issue in the issue tracker or an item in
the [test-runs](Test-Runs) document.*
- *Periodically review the set of possible system configurations to
identify any additional needed test runs.*
### ::Test Runs by Operating System and Browser
| OS \ Browser | IE | Firefox | Safari | Chrome | other |
|----------------|------------------------------------------|----------------------------------|----------------------------------|-----------|---------|
| ::Windows | ::[Passed](Test-Runs#TR-01) | ::[Passed](Test-Runs#TR-02) | ::N/A | ::Pending | ::N/A |
| ::Linux | ::N/A | ::[Passed](Test-Runs#TR-03) | ::Pending | ::Pending | ::N/A |
| ::Mac | ::[FAILED](Test-Runs#TR-10) | ::Pending | ::[Passed](Test-Runs#TR-11) | ::Pending | ::N/A |
| ::iOS | ::N/A | ::N/A | ::Pending | ::N/A | ::N/A |
| ::Android | ::N/A | ::N/A | ::Pending | ::Pending | ::N/A |
### ::Test Runs by Locale
*TIP: Use this outline to guide the testing of internationalized
applications. Each locale indicates a native language as well as formats
for presenting money, dates, times, etc.*
- ::English US: [Passed](Test-Runs#TR-00)
- ::English UK: [Passed](Test-Runs#TR-01)
- ::English CA: [Passed](Test-Runs#TR-02)
- ::Japanese: [Passed](Test-Runs#TR-10)
- ::Spanish: Pending
- ::Russian: Pending
- ::German: Pending
- ::French: Pending
- ::French CA: Waived, French + English Canadian is good enough
### ::Test Runs by Hardware Configuration
*TIP: Use this outline for products that depend on specific hardware.
E.g., a disk crash recovery product would depend on the type of drive, a
game might depend on processor speed and graphics cards, other products
might depend on memory or other hardware specs.*
- ::PCs
- ::IDE drive: Pending
- ::EIDE drive: Waived because we only use IDE features
- ::ATA drive: [Passed](Test-Runs#TR-00)
- ::SCSI drive: [Passed](Test-Runs#TR-01)
- ::SATA drive: [Passed](Test-Runs#TR-02)
- ::USB drive: [FAILED](Test-Runs#TR-03)
- ::Macs
- ::EIDE drive: [Passed](Test-Runs#TR-10)
- ::SCSI drive: [Passed](Test-Runs#TR-11)
- ::Firewire drive: Pending
- ::USB drive: [FAILED](Test-Runs#TR-12)

301
ProductDocumentation/Test-Runs.md Normal file
View File

@ -0,0 +1,301 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [QA Plan](QA-Plan) > [Test Run Suite](Test-Run-Suite) > Test Runs
- [Test suit](Test-Suite)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
*TODO: Use this file to record the results of each test run. Or, use your
issue tracking tool to plan and track test runs.*
### TR-00: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-01: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-02: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Performed all [manual system tests](Test-Cases).
**Test Run Results:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-03: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Performed all [manual system tests](Test-Cases).
**Test Run Results:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-10: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Performed all [manual system tests](Test-Cases).
**Test Run Results:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-11: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Performed all [manual system tests](Test-Cases).
**Test Run Results:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-12: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Performed all [manual system tests](Test-Cases).
**Test Run Results:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-13: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Performed all [manual system tests](Test-Cases).
**Test Run Results:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-20: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Performed all [manual system tests](Test-Cases).
**Test Run Results:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---
### TR-21: Test Run
**Date:**
::DATE-TEST-WAS-PERFORMED
**Tested by:**
:: EMAIL-ADDRESS-OF-TEST-ENGINEER
**Location or Configuration:**
::NAME-OF-SERVER | DESCRIPTION-OF-TEST-ENVIRONMENT
**Test Description:**
::Performed all [manual system tests](Test-Cases).
**Test Run Results:**
::Pending | Passed | FAILED
**Notes and Questions:**
- ::NOTE
- ::QUESTION
---

135
ProductDocumentation/Test-Suite.md Normal file
View File

@ -0,0 +1,135 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [QA Plan](QA-Plan) > Test Suite
- [Test case format](Test-Case-Format)
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
**Process impact:** This is a test suite for manual system testing. It
is just one activity in the overall [QA plan](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, functional area, actor,
business object, or release can help identify parts of the system that
need additional test cases.
*TODO: Before writing individual test cases, list the test cases that you
think you will need. Organize them in a way that will purposely leave
visible blanks on this page if you are missing use cases. Choose one or
more of the organizations show below.*
*TIP: Refer back to your [use cases](Use-Cases) document. Use them
for ideas and make sure that you cover all of them. Remember that test
cases are more precise than use cases, test cases should reference
specific details of your implementation, and there may be several test
cases for a given use case.*
*TIP: The test case suite can be organized into nested lists according to
other coverage criteria, e.g., by actor. Or, it can be organized into
tables that consider two aspects at a time, e.g., business objects vs.
actor. If a certain section of the tree or table does not need test
cases, explicitly mark it "N/A". Otherwise, if a section needs more test
cases than you have written yet, mark it "TODO". If one cell or list
item contains many tests, break that section out into its own table, as
done for the enrollment feature below.*
### Test Cases by Business Object and Operation
<!-- Hint: turn off word wrapping to edit this big table -->
| BO \ Action | ::add | ::list/browse | ::edit | ::delete | ::search | ::other |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| ::Student | <ul><li>::[student-add-1](Test-Cases#student-add-1)</li><li>::[student-add-2](Test-Cases#student-add-2)</li><li>::[student-add-3](Test-Cases#student-add-3)</li></ul> | ::[student-list-1](Test-Cases#student-list-1) | <ul><li>::[student-edit-1](Test-Cases#student-edit-1)</li><li>::[student-edit-2](Test-Cases#student-edit-2)</li></ul> | ::[student-delete-1](test-casesstudent-delete-1) | <ul><li>::[student-search-1](Test-Cases#student-search-1)</li><li>::[student-search-2](Test-Cases#student-search-2)</li></ul> | ::[See grid below](#enroll-grid) |
| ::Course | <ul><li>::[course-add-1](Test-Cases#course-add-1)</li><li>::[course-add-2](Test-Cases#course-add-2)</li></ul> | ::[course-list-1](Test-Cases#course-list-1) | <ul><li>::[course-edit-1](Test-Cases#course-edit-1)</li><li>::[course-move-1](Test-Cases#course-move-1)</li><li>::[course-add-prereq-1](Test-Cases#course-add-prereq-1)</li></ul> | ::[course-cancel-1](Test-Cases#course-cancel-1) | ::[course-search-1](Test-Cases#course-search-1) | ::N/A |
| ::Room | <ul><li>::[room-add-1](Test-Cases#room-add-1)</li><li>::[room-add-2](Test-Cases#room-add-2)</li></ul> | ::[room-list-1](Test-Cases#room-list-1) | ::TODO | ::TODO | ::TODO | ::N/A |
| ::Instructor | ::[inst-add-1](Test-Cases#inst-add-1) | ::N/A | ::[inst-edit-1](Test-Cases#inst-edit-1) | ::[inst-delete-1](Test-Cases#inst-delete-1) | ::N/A | <ul><li>::[inst-eval-1](Test-Cases#inst-eval-1)</li><li>::[inst-eval-2](Test-Cases#inst-eval-2)</li></ul> |
### ::Test Cases for Enrolling in Courses
| ::Course \ Student | ::New Freshman | ::Senior | ::Any Honors | ::Other |
|--------------------|----------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| ::In Major | [::enroll-priority-2](Test-Cases#enroll-priority-2) | [::enroll-priority-1](Test-Cases#enroll-priority-1) | [::enroll-priority-1](Test-Cases#enroll-priority-1) | <ul><li>[::enroll-1](Test-Cases#enroll-1)</li><li>[::enroll-2](Test-Cases#enroll-2)</li><li>[::enroll-3](Test-Cases#enroll-3)</li></ul> |
| ::Non-Major | [::enroll-priority-2](Test-Cases#enroll-priority-2) | [::enroll-priority-1](Test-Cases#enroll-priority-1) | [::enroll-priority-1](Test-Cases#enroll-priority-1) | <ul><li>[::enroll-1](Test-Cases#enroll-1)</li><li>[::enroll-2](Test-Cases#enroll-2)</li><li>[::enroll-3](Test-Cases#enroll-3)</li></ul> |
| ::Honors Course | [::enroll-priority-1](Test-Cases#enroll-priority-1) | [::enroll-priority-1](Test-Cases#enroll-priority-1) | [::enroll-priority-1](Test-Cases#enroll-priority-1) | [::enroll-restricted-1](Test-Cases#enroll-restricted-1) |
### Test Cases by Feature Priority
*TODO: Use this outline to make sure that high priority features are
adequately tested. List features by priority, and then list the test
cases for each feature. If a feature needs more test cases, note that
with "TODO".*
- Essential
- ::[F-01](features#F-01):
::[student-add-1](Test-Cases#student-add-1)
::[student-add-2](Test-Cases#student-add-2)
::[student-add-3](Test-Cases#student-add-3)
- ::[F-02](features#F-02): [enroll-1](Test-Cases#enroll-1)
::[enroll-2](Test-Cases#enroll-2)
::[enroll-3](Test-Cases#enroll-3)
::[enroll-priority-1](Test-Cases#enroll-priority-1)
::[enroll-priority-2](Test-Cases#enroll-priority-2)
::[enroll-restricted-1](Test-Cases#enroll-restricted-1)
- Expected
- ::[F-22](features#F-22):
::[student-search-1](Test-Cases#student-search-1)
::[student-search-2](Test-Cases#student-search-2)
::[course-search-1](Test-Cases#course-search-1)
- ::[F-23](features#F-23):
::[room-add-1](Test-Cases#room-add-1)
::[room-add-2](Test-Cases#room-add-2)
::[room-edit-1](Test-Cases#room-edit-1) TODO
- Desired
- ::[F-31](features#F-31):
::[inst-eval-1](Test-Cases#inst-eval-1)
::[inst-eval-2](Test-Cases#inst-eval-2)
### Test Cases by Use Case Priority
*TODO: Use this outline to make sure that high priority use cases are
adequately tested. List use cases by priority, and then list the test
cases for each use case. If a use case needs more test cases, note that
with "TODO".*
- Essential
- ::[UC-01](Use-Cases#UC-01)
- ::[student-add-1](Test-Cases#student-add-1)
- ::[student-add-2](Test-Cases#student-add-2)
- ::[student-add-3](Test-Cases#student-add-3)
- ::[UC-02](Use-Cases#UC-02)
- ::[enroll-1](Test-Cases#enroll-1)
- ::[UC-03](Use-Cases#UC-03)
- ::[enroll-2](Test-Cases#enroll-2)
- ::[UC-04](Use-Cases#UC-04)
- ::[enroll-3](Test-Cases#enroll-3)
- ::[UC-05](Use-Cases#UC-05)
- ::[enroll-priority-1](Test-Cases#enroll-priority-1)
- ::[enroll-priority-2](Test-Cases#enroll-priority-2)
- ::[UC-06](Use-Cases#UC-06)
- ::[enroll-restricted-1](Test-Cases#enroll-restricted-1)
- Expected
- ::[UC-22](Use-Cases#UC-22):
::[student-search-1](Test-Cases#student-search-1)
::[student-search-2](Test-Cases#student-search-2)
- ::[UC-23](Use-Cases#UC-23):
::[course-search-1](Test-Cases#course-search-1)
- ::[UC-30](Use-Cases#UC-30):
::[room-add-1](Test-Cases#room-add-1)
::[room-add-2](Test-Cases#room-add-2)
- ::[UC-31](Use-Cases#UC-31):
::[room-edit-1](Test-Cases#room-edit-1) TODO
- ::[UC-32](Use-Cases#UC-32): TODO
- ::[UC-33](Use-Cases#UC-33): TODO
- Desired
- ::[UC-40](Use-Cases#UC-40):
::[inst-eval-1](Test-Cases#inst-eval-1)
::[inst-eval-2](Test-Cases#inst-eval-2)

144
ProductDocumentation/Use-Case-Format.md Normal file
View File

@ -0,0 +1,144 @@
##### Related Documents
- [SRS](SRS) > [Use Case Suite](Use-Case-Suite) > Use Case Format
---
**Process impact:** This reference page documents the format of use
cases and gives tips on writing use cases. You can copy and paste the
sample use case into your [Use Cases](Use-Cases) document. This
file itself should not be edited to hold specific use cases.
*TODO: Use this template once in your [Use Cases](Use-Cases)
document. Anything you mention here will apply to all use cases in that
file.*
---
### Aspects common to all use cases
**Direct Actors:**
- ::User: end-user in any role
- ::System: The system being built
- ::When actors are not listed, assume User is doing it.
- ::Items beginning with &quot;see&quot; indicate that System has presented a new screen.
**Stakeholders:**
::The user who is entering the data, and those who will read it
**Prerequisite:**
::Project is set up
*TODO: Copy and paste this use case template as many times as needed in
your [Use Cases](Use-Cases) document. Only use those fields that
are not the same as the default for all use cases.*
---
### UC-00: USE CASE NAME
**Summary:**
::1-3 SENTENCES
**Priority:**
::Essential | Expected | Desired | Optional
**Use Frequency:**
::Always | Often | Sometimes | Rarely | Once
**Direct Actors:**
::ACTOR1, ACTOR2, ACTOR3
**Stakeholders:**
::STAKEHOLDER, STAKEHOLDER, STAKEHOLDER
**Prerequisite:**
- ::PRECONDITION
- ::PRECONDITION
- ::PRECONDITION
**Main Success Scenario:**
- ::STEP
- ::STEP
- ::STEP
**Alternative Scenario Extensions:**
- ::If CONDITION, then ALTERNATIVE STEPS.
- ::NOTES or DETAILS.
- ::If CONDITION, then ALTERNATIVE STEPS.
- ::NOTES or DETAILS.
**Notes and Questions:**
- ::NOTE
- ::NOTE
- ::QUESTION
- ::QUESTION
---
### Format of Use Case Steps
Try to start each step with one of these action words:
#### login \[as ROLE or USER\]
Log into the system with a given user or a user of the given type.
Usually usually only stated explicitly when the test case involves a
workflow between different users.
#### visit LOCATION
Visit a page or GUI window. State the user's intention, don't say
too much about UI choices that could change later. E.g., WRONG:
"Press the 'Advanced...' button on the File | Page Setup dialog".
RIGHT: "Visit the page margin configuration dialog".
#### enter INFORMATION
Fill in specific information. Try to state the information in
some detail. E.g., WRONG: "Enter customer information." RIGHT:
"Enter customer shipping address and discount code." Don't commit to
details of a particular UI, i.e., don't name specific UI fields that
might change later.
#### COMMAND
Describe a command that the user can tell the system to do. State
the user's intent, not the label on a particular UI widget. This
will usually be followed by a "see" step where the user sees a
confirmation of their action. E.g., WRONG: "Control-P, OK". RIGHT:
"Print the current document with default settings".
#### see CONTENT
The user should see the specified information on the currently
presented web page or GUI window. Try to be specific about the
information that is seen, but try not to refer to specific
UI elements. E.g., WRONG: "see UserList.jsp" (what is the user
supposed to notice on that page?) RIGHT: "see list of users with the
newly added user in the list".
#### perform USE-CASE-NAME
This is like a subroutine call. The user will do all the steps of
the named use case and then continue on with the next step of this
use case.
### Further Information
For more information on advice, see:
- Words of wisdom on [use case suites](http://readyset.tigris.org/words-of-wisdom/use-case-suite.html).
- Words of wisdom on [use cases](http://readyset.tigris.org/words-of-wisdom/use-cases.html).

145
ProductDocumentation/Use-Case-Suite.md Normal file
View File

@ -0,0 +1,145 @@
##### Project
::[PROJECT-NAME](Home)
##### Internal Release Number
::X.Y.Z
##### Related Documents
- [SRS](SRS) > Use Case Suite
- [Project proposal](Proposal) > [User needs](User-Needs)
- [SRS](SRS) > [Feature set](Feature-Set)
- [Use case format](Use-Case-Format)
- ::LINK TO USE CASE DIAGRAM
- ::LINKS TO RELEVANT STANDARDS
- ::LINKS TO OTHER DOCUMENTS
---
**Process impact:** 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, functional area, actor, business object, or
release can help identify parts of the system that need additional use
cases.
*TODO: Before writing individual use cases, list the use cases that you
think you will need. Organize them in a way that will purposely leave
visible blanks on this page if you are missing use cases. E.g., see
"Scalability and availability". Choose one or more of the organizations
show below.*
*TIP: Refer back to the user stories in your [user needs](User-Needs)
document. Use them for ideas and make sure that you cover all of them.
Remember that use cases are more precise than user stories, and there
may be several use cases for a given user story.*
*TIP: The use case suite can be organized into nested lists according to
other coverage criteria, e.g., by actor. Or, it can be organized into
tables that consider two aspects at a time, e.g., business objects vs.
actor. If a certain section of the tree or table does not need use
cases, explicitly mark it "N/A". Otherwise, mark it "TODO".*
### Use Cases by Functional Area
- ::User account management
- ::[UC-00](Use-Cases#UC-00) Configure the site
- ::[UC-01](Use-Cases#UC-01) Register as a new user
- ::[UC-02](Use-Cases#UC-02) Request new password
- ::[UC-03](Use-Cases#UC-03) Edit user profile
- ::[UC-04](Use-Cases#UC-04) View user profile
- ::Course management
- ::[UC-10](Use-Cases#UC-10) Create course
- ::[UC-11](Use-Cases#UC-11) View catalog description
- ::[UC-31](Use-Cases#UC-31) Assign course to room
- ::Course enrollment
- ::[UC-20](Use-Cases#UC-20) Enroll in course
- ::[UC-21](Use-Cases#UC-21) Drop course
- ::Scalability and availability
- ::N/A: These features are completely automated and internal, users never interact with them
- ::Facilities management
- ::[UC-30](Use-Cases#UC-30) View room description
- ::[UC-31](Use-Cases#UC-31) Assign course to room
- ::Grading and transcripts
- ::TODO: need to write use cases here
- ::FUNCTIONAL AREA SEVEN
- ::[UC-70](Use-Cases#UC-70) NAME OF USE CASE
- ::[UC-71](Use-Cases#UC-71) NAME OF USE CASE
- ::FUNCTIONAL AREA EIGHT
- ::[UC-80](Use-Cases#UC-80) NAME OF USE CASE
- ::[UC-81](Use-Cases#UC-81) NAME OF USE CASE
- ::FUNCTIONAL AREA NINE
- ::[UC-90](Use-Cases#UC-90) NAME OF USE CASE
- ::[UC-91](Use-Cases#UC-91) NAME OF USE CASE
### Use Cases by Stakeholder
This information is shown in the [use case diagram](LINK-TO-DIAGRAM),
but it is shown here as a list or table so that missing use cases are
more noticeable.
- ::All Stakeholders
- ::[UC-11](Use-Cases#UC-11) View catalog description
- ::[UC-30](Use-Cases#UC-30) View room description
- ::Students
- ::[UC-01](Use-Cases#UC-01) Register as a new user
- ::[UC-02](Use-Cases#UC-02) Request new password
- ::[UC-03](Use-Cases#UC-03) Edit user profile
- ::[UC-20](Use-Cases#UC-20) Enroll in course
- ::[UC-21](Use-Cases#UC-21) Drop course
- ::Instructors
- ::[UC-04](Use-Cases#UC-04) View user profile
- ::Administrators
- ::[UC-00](Use-Cases#UC-00) Configure the site
- ::[UC-10](Use-Cases#UC-10) Create course
- ::[UC-31](Use-Cases#UC-31) Assign course to room
- ::Executives
- ::N/A: this stakeholder never directly interacts with the system
- ::Vendors
- ::TODO: need to write use cases here
- ::STAKEHOLDER
- ::[UC-70](Use-Cases#UC-70) NAME OF USE CASE
- ::[UC-71](Use-Cases#UC-71) NAME OF USE CASE
- ::STAKEHOLDER
- ::[UC-80](Use-Cases#UC-80) NAME OF USE CASE
- ::[UC-81](Use-Cases#UC-81) NAME OF USE CASE
- ::STAKEHOLDER
- ::[UC-90](Use-Cases#UC-90) NAME OF USE CASE
- ::[UC-91](Use-Cases#UC-91) NAME OF USE CASE
### Use Cases by Priority
- Essential
- ::[UC-00](Use-Cases#UC-00) Configure the site
- ::[UC-01](Use-Cases#UC-01) Register as a new user
- ::[UC-10](Use-Cases#UC-10) Create course
- ::[UC-11](Use-Cases#UC-11) View catalog description
- ::[UC-20](Use-Cases#UC-20) Enroll in course
- ::[UC-21](Use-Cases#UC-21) Drop course
- ::[UC-30](Use-Cases#UC-30) Assign course to room
- ::[UC-31](Use-Cases#UC-31) Assign course to room
- Expected
- ::[UC-02](Use-Cases#UC-02) Request new password
- ::[UC-03](Use-Cases#UC-03) Edit user profile
- ::[UC-04](Use-Cases#UC-04) View user profile
- ::[UC-70](Use-Cases#UC-70) NAME OF USE CASE
- ::[UC-71](Use-Cases#UC-71) NAME OF USE CASE
- ::[UC-80](Use-Cases#UC-80) NAME OF USE CASE
- ::[UC-81](Use-Cases#UC-81) NAME OF USE CASE
- Desired
- ::N/A: There are no use cases with Priority = Desired
- Optional
- ::[UC-30](Use-Cases#UC-30) View room description
- ::[UC-90](Use-Cases#UC-90) NAME OF USE CASE
- ::[UC-91](Use-Cases#UC-91) NAME OF USE CASE
### Use Cases by Business Object and Actor
<!-- Hint: turn off text wrap for this large table -->
| BO \ Actor | All | ::Student | ::Instructor | ::Admin |
|--------------------------------|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-----------------------------------------------------------------------------------------------|
| ::Student record | ::N/A | <ul><li>::[Register as new user](Use-Cases#uc-01)</li><li>::[Request new password](Use-Cases#uc-02)</li><li>::[Edit user profile](Use-Cases#uc-03)</li></ul> | ::[View user profile](Use-Cases#uc-04) | ::N/A |
| ::Course | ::[View catalog description](Use-Cases#uc-11) | <ul><li>::[Enroll in course](Use-Cases#uc-20)</li><li>::[Drop course](Use-Cases#uc-21)</li></ul> | ::TODO | <ul><li>::[Create course](Use-Cases#uc-10)</li><li>::[Assign room](Use-Cases#uc-31)</li></ul> |
| ::Room | ::[View room description](Use-Cases#uc-30) | ::N/A | ::N/A | ::[Assign room](Use-Cases#uc-31) |

1218
ProductDocumentation/Use-Cases.md Normal file
View File

File diff suppressed because it is too large Load Diff

51
ProductDocumentation/User-Guide.md Normal file
View File

@ -0,0 +1,51 @@
*TODO: Fill in information on this product. Make sure to use the
**product** name and **external** release number, not internal
information.*
##### Product
::[PRODUCT-NAME](http://www.COMPANY.com/products/PRODUCT-NAME/)
##### Release Number
::X.Y.Z
##### Release Date
::YEAR/MONTH/DAY
##### Customer Support
::For more information or support, please visit our
[website](http://www.COMPANY.com/products/PRODUCT-NAME/) or email
us at <support@COMPANY.com>
---
### Table of Contents
*TODO: Fill in the user guide outline below.*
*TIP: Consider providing both tutorial (step-by-step) and reference
material. You can organize the user guide by features, by use cases, by
roles, or in other ways.*
1. Introduction
- ::What is PRODUCT-NAME?
- ::About this user guide
2. ::SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
3. ::SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
4. ::SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME
- ::SUB-SECTION-NAME

235
ProductDocumentation/User-Needs.md Normal file
View File

@ -0,0 +1,235 @@
##### Project
::[PROJECT-NAME](Home)
##### Attached worksheets
- User needs > [Interview notes](interview-notes.html)
##### Related Documents
- [Project proposal](Proposal) > [Target audience and benefits](Target-and-Benefits)
- [Software requirements specification](SRS)
- [Glossary](Glossary)
---
**Process impact:** The statement of user needs documents 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](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.
### Agreed Goals
*TODO: Has there been a clear statement of the overall goal of this
project that the stakeholders agree to? If so, paste it here or add a
hyperlink. If not, you should summarize your understanding of the
project goals into a brief statement and try to get the stakeholders to
agree to it. The text below gives three alternative examples, select
one, or write your own.*
::We were given an [initial project description](LINK) that is agreed to
by all stakeholders.
::After several interviews and brainstorming sessions, we have [revised
project description](LINK) that has been agreed to by all stakeholders.
::There are still a few different (but overlapping) visions of what this
project needs to achieve. When a single joint vision is agreed to, it
will be hyper-linked from here.
### Environment
*TODO: Briefly describe various aspects of the environment where the
software will be used. Describe the environment as it *is* or *will be*,
not what you would wish it to become. The text below gives a few
examples.*
#### What is the system's business environment?
:: Each real estate agent works with a set of potential buyers
and sellers. Real estate agents do not share customer data with
other agents, because they do not want to share commissions.
Information on specific available homes changes daily, and this tool
must help them keep up.
:: Game players may visit several free web sites to find information
about teams or "clans". There is usually more information available
than they would choose to read, the challenge is in having the most
fun with the least effort. This website must be familiar to players
who have used other sites, but it must also be better.
#### What is the system's physical environment?
:: This system is a web server that will run on a machine in a
co-located data center with 24x7 monitoring, UPS,
air-conditioning, etc. Users of this system are typically at
their offices.
:: This application runs on hand-held devices that will often be used
while the user is walking from one section of the warehouse
to another. Lighting is good in that environment, but there are many
noises and distractions.
#### What is the system's technology environment (hardware and software)?
:: 60% of game players have machines with P-II or equivalent
processors, while 30% have P-I machines, and 10% have less
powerful machines. While many users have 17-inch monitors, 15-inch
monitors or laptops with 1024x768 resolution are also common.
:: 65% of game players are using Windows 98 or Me. 30% are using NT,
2000, or XP. The remaining 5% use Mac OS X, Mac OS 9, or Linux.
### Stakeholders / Actors
*TODO: List and describe the stakeholders for this product. These can be
named individuals or roles that people play. For each stakeholder,
list/rank their key needs. Consider the expected technical expertise of
the stakeholders and how often they are likely to use the system, as
well as key strengths, weaknesses, preferences, or other
characteristics. Use a greater-than sign to indicate inheritance among
types of actors.*
*TIP: To get information on types of users, you can talk to actual users.
You may also want to talk to user surrogates (people who work with
users), such as domain experts, technical trainers, technical support
staff, technical writers, supervisors of users, and your own sales and
marketing department. You can find clues in manuals and marketing
materials for competing products.*
#### ::All
:: All stakeholders share the following key needs:
1. ::Security against abuses by other site visitors
2. ::Convenient access to the site any time over the Internet
#### ::Player
:: Players want to have fun. That means a sense of discovery,
challenge, satisfaction, and community. Some players who become
involved in clans will spend a few hours a week, while others will
spend over 20 hours a week. So, they need new content posted often
to keep them interested. Players involved in clans are often power
users and have high expectations for the functionality and quality
of the site, but they may not have much knowledge of
computer science.
:: Key needs:
1. ::Easily find information about clans
2. ::Keep in touch with members of his/her own clan
3. ::Understand the date and time of tournament play
4. ::Easily report cheaters
#### ::Player > Advanced player
:: Advanced players seek more challenges to continue the sense
of discovery. They tend to play over 20 hours a week. They have seen
more of the game details, now the need to see the "big picture".
:: Key needs:
1. ::View metrics that compare multiple clans
2. ::Understand relationships between clans
3. ::Understand overall schedule of tournaments
#### ::STAKEHOLDER1
::PARAGRAPH
#### ::STAKEHOLDER2
::PARAGRAPH
#### ::STAKEHOLDER3
::PARAGRAPH
### Notes from Interviews and Brainstorming
*TODO: Keep a log of your requirements gathering. Paste in notes from any
face-to-face or telephone conversations with stakeholders or from
brainstorming sessions with members of the development team. If the
communication took place via email, link to it in the archive or paste
it here.*
#### ::DATE, INTERVIEWEE
::[interview with INTERVIEWEE](interview-notes.html)
#### ::DATE-1, INTERVIEWEE
::NOTES FROM INTERVIEW...(pasted here)
#### ::DATE-2, INTERVIEWEE
::NOTES FROM INTERVIEW...(pasted here)
#### ::DATE-3, PARTICIPANTS
::NOTES FROM BRAINSTORMING SESSION...(pasted here)
#### ::DATE-4, PARTICIPANTS
::[email from INTERVIEWEE](LINK-TO-ARCHIVE)
### User Stories
*TODO: Write brief user stories to explain how various actors would
interact with the system (directly and indirectly) to accomplish a
real-world goal. User stories are *not* use cases: user stories are
brief (3-5 sentences) paragraphs that describe one specific scenario in
concrete terms. In this description of user needs, do not make
assumptions about details of the system, instead focus on the users.
Note the source of each user story.*
#### ::invited-to-join
:: John has gotten pretty good at SuperShooter by playing on public
servers about 8 hours a week for the last 3 weeks. John has chatted
with Bob about strategies and they have enjoyed some duels. Bob is a
member of the RedDawn clan. That clan plays a tournament on a
private server Friday nights. Bob invites John to visit the RedDawn
website and join. (Source: [INTERVIEWEE](interview-notes.html))
#### finding-the-tournament
:: Bob is visiting his friend. He tries to use his friend's computer to
log onto the RedDawn SuperShooter tournament. But, he does not
remember the exact name of the server. So, he visits the RedDawn
clan website to find that information. (Source: PERSON-NAME)
#### STORY-NAME-1
:: PARAGRAPH
#### STORY-NAME-2
:: PARAGRAPH
#### STORY-NAME-3
:: PARAGRAPH
### Performance and Capacity Needs
*TODO: Briefly list the stakeholders' desired values for various aspects
of the system capacity. If you have a good idea about averages or rates
of increase, note that as well.*
::By the end of the first year of service, we should to reach the
following system capacity:
- ::50,000 user records in the clan website account database (rate:
50-500 new registrations each day)
- ::1000 users browsing the web site any given time
- ::1000 gaming clans
- ::1000 members of a single clan (average: 8)
- ::4 MB max disk space for each clan (average: 0.5 MB)
- ::100 game vendors posting advertisements on the site
- ::1000 actual advertisements in the database

73
ProductDocumentation/Words-of-Wisdom-Proposal.md Normal file
View File

@ -0,0 +1,73 @@
# Proposal
## Line-by-line Instructions
### Project
Write the name of the proposed project.
### Project Time-frame
Write the proposed project start and end dates. This information will usually be approximate.
### Summary
Write an executive summary of the proposed project. It is usually best to write the proposal first and then write the highlights here.
### What is the setting and history behind this project?
Briefly describe how the need for this project arose and was recognized. This helps motivate the product, put it into the context of the overall business, and can help identify project stakeholders.
### What business problem does this project address?
Use 2-4 sentences to describe the problem that your potential users are having right now. Focus on business problems, not technical problems. If you are trying to solve a technical problem, describe the business need that makes that technical problem important enough to solve. Do not say anything about your solution here.
### What are some current approaches to this problem?
List some of the alternatives that your potential customers have now. Listing these now will help set requirements for your product to be better than these alternatives, and it will help identify the expectations of potential customers that have already been using the alternatives.
### Why is this problem worth solving or worth solving better?
Explain why a better product would matter to customers or project stakeholders. Your argument would ideally impact business metrics such as profit, costs, revenue, sales, time-to-market, brand value, size of customer base, or return on investment.
### How will this product be better than previous approaches?
Describe how this product will actually be better than the current alternatives. This may be due to better functionality ("defining features" are covered below), or other aspects of the product that make it easier to buy, install, or use.
### Where is there more information on this problem?
Link to more information on the problem that customers face. Is this problem growing? Is the problem big enough to create enough demand for the product? These documents should support the decision to authorize the project by explaining the need.
### What is the goal of this project?
Write 2-4 sentences or bullets on your main goal for the project. Briefly, name your target audience and mention key benefits that your customers will gain by using your product.
### What are the defining features and benefits of this product?
Briefly list the most important features of the product. It is alright to reiterate features found in the alternative products, but focus on the unique features that will set this product apart.
### Where are other documents that further explain the goal of this project?
If you have other documents that support this project proposal, link to them from here. These documents should support the decision to authorize the project by explaining the value of the proposed solution.
### Scope
There are several useful formats for explaining the scope of a proposed project. A good scope description provides insight into the resources that may be needed for the project and helps you avoid feature creep later.
The simplest format is just a paragraph: give 2-4 sentences that summarize what you intend to do as part of this project. It is often a good idea to explicitly state some things that will not be done.
Another way to document the scope of a project is to use two bullet lists: one for things that are in scope, and one for things that are out of scope.
The third and best format is a table with columns that list things that are in scope and out of scope. Each row of the table defines a direction, the first column says how far you plan to go in that direction, and the second column names something that is too far in that direction.
### Deliverables
Briefly list the deliverables in enough detail to support the decision to authorize the project. You can describe deliverables in more detail in the project plan.
### Risks and Rewards
Briefly list risks to the success of the project and the main rewards to the organization if the project succeeds. Include enough information to support the decision whether to authorize the project. Later, you can describe and track project risks in more detail in the risk management worksheet.
### Project Plan
Link to a draft of the project plan.

71
ProductDocumentation/Words-of-Wisdom.md Normal file
View File

@ -0,0 +1,71 @@
# Template List
The original [ReadySET Pro](http://readysetpro.com) words of wisdom are [here](http://www.readysetpro.com/words-of-wisdom).
***
The following pages contain specific tips and advice on each template.
## Project kick-off
* [Project proposal](Words-of-Wisdom-Proposal)
* Target audience & benefits
* User needs & stories
* Interview notes
* All-in-one project summary
## Project Reference Information
* Project overview
* Glossary / Data dictionary
* Software development method
## System requirements
* SRS
* Use case suite
* Feature set
## Planning
* Project plan
* Resource needs
* Risk management
* Legal issues
## Design
* Design overview
* Architecture
* Persistence
* User interface
* Security
* Source organization
## Project tracking
* Status report
* Review meeting
## Quality management
* QA plan
* Test suite
* Test run log
## Product content
* Release notes
* Installation / Quick-start
* User Guide
* FAQ / Troubleshooting
## Product support information
* Implementation notes
* Demo script
## Release end-game
* Release checklist
* Postmortem report

127
ProductDocumentation/Workflows.md Normal file
View File

@ -0,0 +1,127 @@
### By Activity
1. Project Planning
1. [Home](Home)
2. [Proposal](Proposal)
- [Target and Benefits](Target-and-Benefits)
3. [Project Plan](Project-Plan)
- [Resource needs](Resource-Needs)
4. [Legal Issues](Legal)
5. [QA Plan](QA-Plan)
2. Requirements and Specification
1. [User Needs](User-Needs)
- [Interview Notes](Interview-Notes)
2. [Software Requirements Specification](SRS)
- [Use Case Suite](Use-Case-Suite)
- [Feature Set](Feature-Set)
3. Architecture and Design
1. [Design](Design)
- [Architecture Worksheet](Design-Architecture)
- [Source and Build](Design-Src-Org)
- [User Interface Worksheet](Design-UI)
- [Persistence Worksheet](Design-Persistence)
- [Security Worksheet](Design-Security)
4. Implementation and Testing
1. [User Guide](User-Guide)
2. [Test Suite](Test-Suite)
- [Test Case Format](Test-Case-Format)
- [Test Cases](Test-Cases)
5. Deployment and Installation
1. [Release Checklist](Release-Checklist)
2. [Installation / Quick Start Guide](Installation-Guide)
3. [Release Notes](Release-Notes)
4. [Demo Script](Demo-Script)
6. Operations and Support
1. [FAQ / Troubleshooting](FAQ)
2. [Implementation Notes](Implementation-Notes)
7. Continuous or Final
1. [Glossary](Glossary)
2. [Status Report](Status-Report)
3. [Review Meeting Notes](Review-Meeting-Notes)
4. [Software Development Methodology](SDM)
### By Suggested Sequence
1. Step 1
1. [Home](Home)
2. [Proposal](Proposal)
- [](Target-and-Benefits)[Target and Benefits](Target-and-Benefits)
3. [Project Plan](Project-Plan)
- [Resource needs](Resource-Needs)
4. [Legal Issues](Legal)
5. [Glossary](Glossary)
2. Step 2
1. [User Needs](User-Needs)
- [Interview Notes](Interview-Notes)
2. [Software Requirements Specification](SRS)
- [Use Case Suite](Use-Case-Suite)
- [Feature Set](Feature-Set)
3. [Software Development Methodology](SDM)
3. Step 3
1. [Design](Design)
- [Architecture Worksheet](Design-Architecture)
- [Source and Build](Design-Src-Org)
- [User Interface Worksheet](Design-UI)
- [Persistence Worksheet](Design-Persistence)
- [Security Worksheet](Design-Security)
4. Step 4
1. [QA Plan](QA-Plan)
2. [Test Suite](Test-Suite)
- [Test Case Format](Test-Case-Format)
- [Test Cases](Test-Cases)
5. Step 5
1. [Review Meeting Notes](Review-Meeting-Notes)
6. Step 6
1. [Release Checklist](Release-Checklist)
7. Step 7
1. [Installation / Quick Start Guide](Installation-Guide)
2. [Release Notes](Release-Notes)
3. [User Guide](User-Guide)
4. [Demo Script](Demo-Script)
5. [FAQ / Troubleshooting](FAQ)
6. [Implementation Notes](Implementation-Notes)
8. Every week
1. [Status Report](Status-Report)
### All Templates
1. [Summary](Summary)
2. [Home](Home)
3. [Proposal](Proposal)
- [Target and Benefits](Target-and-Benefits)
4. [Project Plan](Project-Plan)
- [Resource needs](Resource-Needs)
5. [QA Plan](QA-Plan)
- [Test Suite](Test-Suite)
- [Test Case Format](Test-Case-Format)
- [Test Cases](Test-Cases)
- [Review Meeting Notes](Review-Meeting-Notes)
6. [Legal Issues](Legal)
7. [User Needs](User-Needs)
- [Interview Notes](Interview-Notes)
8. [Software Requirements Specification](SRS)
- [Use Case Suite](Use-Case-Suite)
- [Feature Set](Feature-Set)
9. [Glossary](Glossary)
10. [Design](Design)
- [Architecture Worksheet](Design-Architecture)
- [Source and Build](Design-Src-Org)
- [User Interface Worksheet](Design-UI)
- [Persistence Worksheet](Design-Persistence)
- [Security Worksheet](Design-Security)
11. [User Guide](User-Guide)
12. [Release Checklist](Release-Checklist)
13. [Installation / Quick Start Guide](Installation-Guide)
14. [Release Notes](Release-Notes)
15. [Demo Script](Demo-Script)
16. [FAQ / Troubleshooting](FAQ)
17. [Implementation Notes](Implementation-Notes)
18. [Status Report](Status-Report)
19. [Software Development Methodology](SDM)
### How to download these templates
- [Download template archive](http://readyset.tigris.org/servlets/ProjectDocumentList), or
- Use CVS to [check out](http://readyset.tigris.org/servlets/ProjectSource) project
"readyset" or clone from [ReadySet GFM](https://github.com/bike-bill/readyset-gfm/wiki)
on Github.

7
ProductDocumentation/_Footer.md Normal file
View File

@ -0,0 +1,7 @@
**TODO:** Check for [words of wisdom](Words-of-Wisdom) for additional advice on this template.
::**Your-Organization Proprietary**
Copyright 2003-2004 Jason Robbins. All rights reserved. [License terms](LICENSE). Retain this copyright statement whenever this file is used as a template.
Find [Readyset GFM](https://github.com/bike-bill/readyset-gfm) on Github.

5
ProductDocumentation/_Sidebar.md Normal file
View File

@ -0,0 +1,5 @@
* [Home](Home)
* [Summary](Summary)
* [Project Plan](Project-Plan)
* [Workflows](Workflows)
* [Words of Wisdom](Words-of-Wisdom)