Lecture 2: Design Documentation

Question 1

What is design?

Answer 1

Design is a problem-solving process. Its objective is to find and describe a way:

• to implement the system’s functional requirements.
• to respect the constraints imposed by the non-functional requirements
• to adhere to general principles of ‘good’ quality.

Question 2

What is a software solution?

Answer 2

A software solution is a compromise meeting all aspects:

• implementation of functional requirements.
• with respect to the constraints imposed by the non-functional requirements,
• adhere to general priniciples of ‘good’ quality.

Question 3

What is the goal of documentation?

Answer 3

The goal of documentation is to record and keep current the results of design decisions so that stakeholders find the information they need.

Question 4

What is the result of a software design?

Answer 4

• blueprint for the chosen solution

- design decisions

Question 5

Why is it important to capture the rationale?

Answer 5

Decisions always have some rationale.

Organizations want to be able to reuse, support future change, increase personal effectiveness, use for training.

Question 6

What is Software Design Description (SDD)?

Answer 6

A respresentation of a software design to be used for recording design information and communicating that design information to key design stakeholders.

Question 7

What is a design entity: component?

Answer 7

•  No agreed upon definition
•  Any piece of software or hardware that has a clear role
-  Isolated, replaceable with a different component with equivalent functionality (DB, authentication server)
-  Reusable, generalized to fit in different types of systems (address book – for email, agenda, networking)
•  Special-purpose, providing very specific (and hence expensive) services (e-payment – for e-shopping, pay university fees, taxes)

•   Runtime entity
•   Delivering interfaces accessible during execution; computational unit; independently deployed unit; … [Szyperski 1998]

Question 8

What is the design entity: Module?

Answer 8

Design entity: Module

•   Other side of the medal
•   A component that is defined at the programming language level
•   E.g. methods, classes and packages are modules in Java
•   Design-time entity
•   Delivers properties like encapsulation, information hiding, separation of concerns, …

Question 9

What is a system?

Answer 9

•   A logical entity consisting of hardware, software or both
•   Has a set of responsibilities (goal of requirements analysis).
•   Has a specification implemented by a collection of components.
•   Continues to exist even if its components are changed or replaced.
•   Sub-system:
•   A system that is part of a larger system, and which has a defined interface

Question 10

What is a design view?

Answer 10

•   “A representation comprised of one or more design elements to address a set of design concerns from a specified design viewpoint.”
•   Its purpose is to allow a stakeholder to focus on specific design concerns

Question 11

What is a design viewpoint?

Answer 11

•   “The specification of the elements and conventions available for constructing and using a design view.” [IEEE 1016-2009]
•   Example: interoperability viewpoint (description fragments)

Question 12

What is a design overlay?

Answer 12

•   “A mechanism to organize and present additional design information that does not strictly follow a viewpoint.”
•   E.g. textual description of interoperability view

Question 13

What is a design rationale?

Answer 13

•   “Information capturing the reasoning of the designer that led to the system as designed,
•   including design options, trade-offs considered, decisions made, and the justifications of those decisions.” [1016-2009]

Question 14

To take design decision, what does the software engineer uses?

Answer 14

“current” knowledge:
•  the requirements
•  the design as created so far

“past” knowledge:
•  technology available
•  what has worked well in the past
•  software design principles and “best practices”

Question 15

Seven rules for creating sound documentation

Answer 15

•   Rule 1: write documentation from the reader’s point of view
•   Rule 2: avoid unnecessary repetition
•   Rule 3: avoid ambiguity
•   Define notational conventions, stick to them
•   Rule 4: use a standard organization
•   Organize documentation for ease of reference
•   Put “TBD” where info is (still) unknown
•   Rule 5: record rationale
•   Rule 6: keep documentation current (but not too current)
•   Rule 7: review documentation for fitness of purpose

Question 16

How to review documentation

Answer 16

•  Goal: the design is documented well enough so that people can understand and use it.
•  A review answers questions about documentation’s consistency
- consistent with stakeholder community
- consistent with itself
- consistent with good form
- consistent with the system

Question 17

Goal of presenting design documentation

Answer 17

Goal: help the audience to appreciate the problem, see the solutions chosen, the why, and gain confidence that it is the right solution