document Comparison Table

Object Oriented Software Engineering View all facts Glossary Help

Next representation: documentation Up: representation Previous representation: diagram

document comparison table

Subject make reference to write for include expressed as force keep outline write is a subtopic of test base on review by see also go through has part discuss educate contain ensure list have purpose have suggested structure divide deprecate is a synonym of start give subject to assist with update form show define depend on have parts allow agree to by use have summarize have part has definition write at describe refine be state

architectural model a particular audience several different views such as
The logical breakdown into subsystems, often shown using package diagrams
The dynamics of the interaction among components at run time, expressed using interaction or activity diagrams
The data that will be shared among the subsystems, expressed using class diagrams
The components that will exist at run time, and the machines or devices on which they will be located, expressed using component and deployment diagrams
9.4 - Software Architecture information about the interfaces and dynamic interactions among the subsystems
To enable everyone to better understand the system
To allow people to work on individual pieces of the system in isolation
To prepare for extension of the system
To facilitate reuse and reusability
software architecture^3
integrating the work of individual people to form the final system
planning and co-ordination of the work of developing a complex software system which is distributed among a large number of people
planning the evolution of the system, such as subsystems that are envisioned to be part of a future release
each system component, encouraging reuse the terms that people use when they communicate with each other about lower-level details to communicate with customers The document produced as a result of performing software architecture generic to ensure reusability

catalog of reusable components a particular audience up-to-date 3.2 - Incorporating Reusability and Reuse Into Software Engineering information about reusable components older components that have been found to be unreliable or have been superseded by better components easy to search

design document the requirements that are being implemented by this design
Those who will be implementing the design, i.e. the programmers
Those who will need, in the future, to modify the design
Those who need to create systems or subsystems that interface with the system being designed
information that would be readily obvious to a skilled programmer or designer
details in a design document that would be better placed as comments in the code
details that can be extracted automatically from the code, such as the list of public methods
a designer to be explicit and to consider the important issues before starting implementation 9.1 - The Process of Design design the important issues that had to be resolved, the possible alternatives that were considered, the final decision and the rationale for the decision every design decision along with the reasoning that went into making the decision traceability by making reference to the requirements that are being implemented by this design
to encourage designers to make good design decisions
to communicate the design to others
purpose
general priorities
outline of the design
major design issues
other details of the design
a group of people to review the design and therefore to improve it Documentation produced as a result of the design process what system or part of the system this design document describes

domain analysis document a particular audience 4.1 - Domain Analysis other software engineers who join the team later an excessive amount of detailed information information found during domain analysis
Introduction, including the name of the domain and the motivation for performing the analysis
Glossary which gives the meanings of all terms used in the domain that are either not part of everyday language or else have special meanings
General knowledge about the domain - important facts or rules that are widely known by the domain experts and which would normally be learned as part of their education
Customers and users - who will or might buy the software, and in what industrial sectors they operate. Also, describe the other people who work in the domain, even peripherally.
The environment - equipment and systems used
Tasks and procedures currently performed - what the various people do as they go about their work
Competing software, including advantages and disadvantages
Similarities across domains and organizations - what distinguishes the customer's organization from others, as well as what they have in common

known bugs list a particular audience 10.9 - Strategies for Testing Large Systems A list of defects in a system that have not yet been fixed

license a particular audience 1.3 - Software Engineering as a Branch of the Engineering Profession A legal document authorizing the holder to perform some activity

problem statement a particular audience 4.3 - Defining The Problem and the Scope as early as possible the user's ultimate high-level goal when they use the system, and the customers high-level goal for having it developed to evaluate requirements based on the question: 'are we adequately solving the problem?' several times

project plan a particular audience the present cost estimates for the tasks and subsystems, showing all calculations, and including pessimistic and optimistic values the techniques to be employed for requirements gathering, design, implementation, quality assurance, change management; risk management, and ongoing project management; documents to be produced, including contents of these documents; ways to measure and track the project 11.6 - Contents of a Project Plan
Purpose
Background information
Processes to be used
Subsystems and planned releases
Risks and challenges
Tasks
Cost estimates
Team
Schedule and milestones
the tasks to be completed for each subsystem and release the system into subsystems and releases, that can be allocated to people or teams references to related projects and any documents produced so far, such as requirements definitions A document used in project management describing all aspects of the project's process, including the process model, tasks, risks, cost estimates, team structure and schedule the stakeholders the business objectives for the project, including quantified anticipated benefits

release notes a particular audience 10.9 - Strategies for Testing Large Systems A document describing a particular release of software, including a known bugs list

requirements document a particular audience 4.7 - Types of Requirements Document the author and stakeholders several iterations of development and review non-functional requirements requirements in the introduction and conclusion to avoid the problem of changing the requirements in one place and forgetting to change them in another place change caused by:
Business process change
Technology change
Better understanding of the problem
when incremental changes are made to the system the basis for testing the system
The size of the system
The need to interface to other systems
The target audience
The contractual arrangements for development
The stage in requirements gathering
The level of experience with the domain and the technology
The cost incurred if the requirements are faulty
a clear title, and sections with meaningful headings and subheadings all the stakeholders changes in each new version highlighted for the reader using change bars Any document describing a set of requirements a high-enough level so that the potential users can read it well organized

specification a particular audience 4.7 - Types of Requirements Document A document that gives complete detail about something. Normally implicitly means requirements specification, but the term design specification is sometimes also used to mean a detailed and precise design document

standard a particular audience 4.13 - Developing Requirements - References A document describing a body of well-respected information that engineers should conform to in order to ensure they are following best-practice, and will consistently produce good-quality products

test plan a particular audience long before the testing starts 10.8 - Writing Formal Test Cases and Test Plans explicit and explicit attributes use cases once the requirements are developed A document that contains a complete set of test cases for a system, along with other information about the testing process

Next representation: documentation Up: representation Previous representation: diagram

Subject	make reference to	write for	include	expressed as	force	keep	outline	write	is a subtopic of	test	base on	review by	see also	go through	has part	discuss	educate	contain	ensure	list	have purpose	have suggested structure	divide	deprecate	is a synonym of	start	give	subject to	assist with	update	form	show	define	depend on	have parts	allow	agree to by	use	have	summarize	have part	has definition	write at	describe	refine	be	state
architectural model		a particular audience		several different views such as The logical breakdown into subsystems, often shown using package diagrams The dynamics of the interaction among components at run time, expressed using interaction or activity diagrams The data that will be shared among the subsystems, expressed using class diagrams The components that will exist at run time, and the machines or devices on which they will be located, expressed using component and deployment diagrams					9.4 - Software Architecture									information about the interfaces and dynamic interactions among the subsystems			To enable everyone to better understand the system To allow people to work on individual pieces of the system in isolation To prepare for extension of the system To facilitate reuse and reusability				software architecture^3				integrating the work of individual people to form the final system planning and co-ordination of the work of developing a complex software system which is distributed among a large number of people planning the evolution of the system, such as subsystems that are envisioned to be part of a future release			each system component, encouraging reuse	the terms that people use when they communicate with each other about lower-level details					to communicate with customers				The document produced as a result of performing software architecture				generic to ensure reusability
catalog of reusable components		a particular audience				up-to-date			3.2 - Incorporating Reusability and Reuse Into Software Engineering									information about reusable components						older components that have been found to be unreliable or have been superseded by better components																						easy to search
design document	the requirements that are being implemented by this design	Those who will be implementing the design, i.e. the programmers Those who will need, in the future, to modify the design Those who need to create systems or subsystems that interface with the system being designed	information that would be readily obvious to a skilled programmer or designer details in a design document that would be better placed as comments in the code details that can be extracted automatically from the code, such as the list of public methods		a designer to be explicit and to consider the important issues before starting implementation				9.1 - The Process of Design				design			the important issues that had to be resolved, the possible alternatives that were considered, the final decision and the rationale for the decision		every design decision along with the reasoning that went into making the decision	traceability by making reference to the requirements that are being implemented by this design		to encourage designers to make good design decisions to communicate the design to others	purpose general priorities outline of the design major design issues other details of the design														a group of people to review the design and therefore to improve it						Documentation produced as a result of the design process		what system or part of the system this design document describes
domain analysis document		a particular audience							4.1 - Domain Analysis								other software engineers who join the team later	an excessive amount of detailed information																						information found during domain analysis	Introduction, including the name of the domain and the motivation for performing the analysis Glossary which gives the meanings of all terms used in the domain that are either not part of everyday language or else have special meanings General knowledge about the domain - important facts or rules that are widely known by the domain experts and which would normally be learned as part of their education Customers and users - who will or might buy the software, and in what industrial sectors they operate. Also, describe the other people who work in the domain, even peripherally. The environment - equipment and systems used Tasks and procedures currently performed - what the various people do as they go about their work Competing software, including advantages and disadvantages Similarities across domains and organizations - what distinguishes the customer's organization from others, as well as what they have in common
known bugs list		a particular audience							10.9 - Strategies for Testing Large Systems																																	A list of defects in a system that have not yet been fixed
license		a particular audience							1.3 - Software Engineering as a Branch of the Engineering Profession																																	A legal document authorizing the holder to perform some activity
problem statement		a particular audience							4.3 - Defining The Problem and the Scope																								as early as possible	the user's ultimate high-level goal when they use the system, and the customers high-level goal for having it developed				to evaluate requirements based on the question: 'are we adequately solving the problem?'							several times
project plan		a particular audience	the present cost estimates for the tasks and subsystems, showing all calculations, and including pessimistic and optimistic values				the techniques to be employed for requirements gathering, design, implementation, quality assurance, change management; risk management, and ongoing project management; documents to be produced, including contents of these documents; ways to measure and track the project		11.6 - Contents of a Project Plan									Purpose Background information Processes to be used Subsystems and planned releases Risks and challenges Tasks Cost estimates Team Schedule and milestones		the tasks to be completed for each subsystem and release			the system into subsystems and releases, that can be allocated to people or teams				references to related projects and any documents produced so far, such as requirements definitions															A document used in project management describing all aspects of the project's process, including the process model, tasks, risks, cost estimates, team structure and schedule		the stakeholders			the business objectives for the project, including quantified anticipated benefits
release notes		a particular audience							10.9 - Strategies for Testing Large Systems																																	A document describing a particular release of software, including a known bugs list
requirements document		a particular audience							4.7 - Types of Requirements Document			the author and stakeholders		several iterations of development and review	non-functional requirements			requirements in the introduction and conclusion to avoid the problem of changing the requirements in one place and forgetting to change them in another place										change caused by: Business process change Technology change Better understanding of the problem		when incremental changes are made to the system	the basis for testing the system			The size of the system The need to interface to other systems The target audience The contractual arrangements for development The stage in requirements gathering The level of experience with the domain and the technology The cost incurred if the requirements are faulty	a clear title, and sections with meaningful headings and subheadings		all the stakeholders		changes in each new version highlighted for the reader using change bars			Any document describing a set of requirements	a high-enough level so that the potential users can read it			well organized
specification		a particular audience							4.7 - Types of Requirements Document																																	A document that gives complete detail about something. Normally implicitly means requirements specification, but the term design specification is sometimes also used to mean a detailed and precise design document
standard		a particular audience							4.13 - Developing Requirements - References																																	A document describing a body of well-respected information that engineers should conform to in order to ensure they are following best-practice, and will consistently produce good-quality products
test plan		a particular audience						long before the testing starts	10.8 - Writing Formal Test Cases and Test Plans	explicit and explicit attributes	use cases															once the requirements are developed																A document that contains a complete set of test cases for a system, along with other information about the testing process