Architecture Documentation and Technical/cross-cutting concepts

Question 1

Name examples for technical/cross-cutting concerns

Answer 1

• flow control
• error handling
• security
• monitoring
• integration
• internationalization
• persistence
• deployment

Question 2

What is the base principle of cross-cutting concerns?

Answer 2

• often used in most subareas of software system
• but are themselves independent from another (except for selective interaction)
• can be mapped across different dimensions in diagrams without great overlay

Question 3

What are typical error handling tasks?

Answer 3

• Identifying error cause
• Defining appropriate reactions to dealing with errors:
• 1. Classification into categories and severity levels
• 2. Differentiation between technical and functional errors
• Minimizing the impact of the error
• Making diagnosis of error causes easier
• 1. What went wrong?
• 2. Where did it happen?
• 3. Why did it happen?
• Using error prevention by the software system (processing tolerances, early warnings)
• Defining technology for error handling
• ensure end-to-end error handling

Question 4

What are a minimum amount of security issues to be considered?

Answer 4

• Authentication
• Authorization
• Integrity
• Availability
• Confidentiality
• Non-repudiation

Question 5

How should the relationship between Architecture plan and implementation should be specifeid?

Answer 5

• documents where the mapping between architecture plan and implementation are described are extremely useful
• should be formulated in rules/specifications
• for example, that a UML component diagram itself is always implemented as its own package
• this allows a direct correlation between diagrams and code

Question 6

What types of documents are usual for software architectures?

Answer 6

• central architecture description
• architecture overview
• documentation overview
• documentation handbook
• architecture wallpaper
• overview presentation (2 variants)
• Architecture Decision record
• Technical Information

Question 7

What is the Central architecture description?

Answer 7

• core document for software architecture
• all information with relevance to architecture

Question 8

Name examples for the information contained in the Central Architecture Description

Answer 8

• Architectures task, objectives, quality requierements and stakeholders
• Technical and organizational conditions and constraints
• Views, decisions, patterns used
• Technical concepts
• Quality evaluations
• identified risks

Question 9

What is the Architecture overview document?

Answer 9

• brief, easy-to-read summary of central architecture description
• max. 30 pages
• similiar contents like central architecture description, but focus on certain elements
• if not possible to create central architecture description, this can be created instead, pared-down alternative to a complete description

Question 10

What does the architecture overview document focus on?

Answer 10

• central views
• main requirements
• core decisions

Question 11

What is the document overview document and what purpose does it serve?

Answer 11

• either per-project or per-application
• directory that serves as index of all architecture-relevant documents and documents and their dependencies
• organizational policies on where this directory is to be found and how it should be structured should be given
• including information on which documents should be read by whom

Question 12

What is the overview presentation document?

Answer 12

• presentation slides with most important aspects of architecture for management target group
• two versions:
• 1. max. 1 hour, with technical info, presentation of architecture
• 2. concise, max. 10 min with central statements and business benefit

Question 13

What is the Architecture wallpaper document?

Answer 13

• used to present complete overview of a large number of architecture aspects
• usually collection of poster-sized prints detailing views with refinements, quality aspects and so on
• used for interactive discussions of specific topics
• not be-all and end-all solution, can have deterrent effect on those focused on implementation, testing, operating the system

Question 14

What is the document handbook document?

Answer 14

• explains structure and function of complete project documentation
• explains the notations used

Question 15

What is an Architecture Decision Record (ADR)

Answer 15

• fixed format for documenting architectural decisions made
• shows the decisions in isolation in its own document or section

Question 16

What does an ADR focus on beside the result of the decision?

Answer 16

• assumptions made
• motives
• influencing factors

at the time of decision

Question 17

What does an ADR consist of?

Answer 17

• Title: info about topic
• Context: what influences decision, representation of circumstances and a list of boundary conditions or previous decisions that lead to the current need for a decision
• Decision: answer to previous sections, available discussions often listed and discussed here
• Status: info whether decision is in effect, a suggestion or already outdated
• Consequences: how context changes as result of decision, including positive and negative effect of decision to ensure comprehensibility

Question 18

What is contained in the Technical information document?

Answer 18

• one or more documents containing important decisions for project developers and testers
• should store programming guidelines, development methods
• as well as info about building, starting and testing of the system

Question 19

What is important about the documentation of external interfaces?

Answer 19

• extra care and time should be spent early in the project on interface documentation
• much better than later in the project

Question 20

What information should be part of an Interface documentation template?

Answer 20

• Identification
• Resouces provided
• Error scenarios
• Variability and configuration
• Quality characteristics
• Design decisions
• Notes

Question 21

What are Best-practice rules for documentation?

Answer 21

1. Write from readers perspective
2. Avoid unnecessary repitition
3. Avoid ambiguity
4. Standardized Organizational structure or templates
5. Justify important decisions in writing
6. Check the documentation’s suitability for use
7. Unclutterd diagrams
8. Regular Updates
9. Adapt the changeability of the documentation to the architecture

Question 22

Under what circumstances would it be acceptable to allow repition inside documentation? (2.)

Answer 22

Only if they do:
- simplify the use of the documentation
- Significantly simplify its maintenance and updating

Question 23

What do you have to think about when repitition occurs with only slight variations?

Answer 23

• is the variation intentional
• should importance be attached to this variation

documentation from different perspectives is not repitition but helps to deepen the understanding.

Question 24

How do you Avoid ambiguity in Architecture documentation? (3.)

Answer 24

• use formal description languages
• when symbolic notations (e.g. UML) are used, symbols should be explained or a reference to an explanatory source should be included
• in verbal and written communication the identical terms and arguments should be used

Question 25

What is important about the justification of architectural decisions in writing? (5)

Answer 25

- brief justification is important - can be done via e.g. reference to relevant company policy - can also describe rejected solutions alternatives - can also contain advantages and disadvantages of current solution - saves time, especially when decisions have to be reconsidered under changed circumstances

Question 26

What is important about checking the documentations suitablity for use? (6.)

Answer 26

- reviews should be carried out be suitable representatives - review process itself should be reviewed - improvement process for regular cheks of documentation policies should be implemented

Question 27

What is important about Uncluttered diagrams? (7.)

Answer 27

- the human mind can process about 5-9 elements comprehensively - more elements should be split into distinct diagrams, if possible

Question 28

What is important about Regular Updates of software architectures (8.)?

Answer 28

- process that updates documentation after change should be established - for regular updates during development and maintenance - its useful to define fixed synchronization deadlines for updates

Question 29

What is important about Adapting the changeability of the documentation to the architecture?

Answer 29

- level of formalization should be adapted to project circumstances - first draft change quickly and often, later changes appear less often several adjustment options are available: - level of detail - format - accessibility - formality of diagrams - length of review/change/release process