Skip to content

Commit

Permalink
Updates
Browse files Browse the repository at this point in the history
  • Loading branch information
Abel Menéndez Hernández authored and Abel Menéndez Hernández committed Feb 16, 2024
1 parent 8b66f0e commit d59ee76
Showing 1 changed file with 268 additions and 14 deletions.
282 changes: 268 additions & 14 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -808,6 +808,30 @@ <h3 id="_stakeholders">1.3. Stakeholders</h3>
<div class="sect1">
<h2 id="section-architecture-constraints">2. Architecture Constraints</h2>
<div class="sectionbody">
<div class="sidebarblock arc42help">
<div class="content">
<div class="paragraph">
<div class="title">Contents</div>
<p>Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>Architects should know exactly where they are free in their design decisions and where they must adhere to constraints.
Constraints must always be dealt with; they may be negotiable, though.</p>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>Simple tables of constraints with explanations.
If needed you can subdivide them into
technical constraints, organizational and political constraints and
conventions (e.g. programming or versioning guidelines, documentation or naming conventions)</p>
</div>
<div class="paragraph">
<div class="title">Further Information</div>
<p>See <a href="https://docs.arc42.org/section-2/">Architecture Constraints</a> in the arc42 documentation.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_technical_constraints">2.1. Technical constraints</h3>
<table class="tableblock frame-all grid-all stretch">
Expand Down Expand Up @@ -940,26 +964,72 @@ <h2 id="section-system-scope-and-context">3. System Scope and Context</h2>
<div class="sidebarblock arc42help">
<div class="content">
<div class="paragraph">
<p>g</p>
<div class="title">Contents</div>
<p>System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners
(neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.</p>
</div>
<div class="paragraph">
<p>If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>The domain interfaces and technical interfaces to communication partners are among your system&#8217;s most critical aspects. Make sure that you completely understand them.</p>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>Various options:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Context diagrams</p>
</li>
<li>
<p>Lists of communication partners and their interfaces.</p>
</li>
</ul>
</div>
<div class="paragraph">
<div class="title">Further Information</div>
<p>See <a href="https://docs.arc42.org/section-3/">Context and Scope</a> in the arc42 documentation.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_business_context">3.1. Business Context</h3>
<div class="sidebarblock arc42help">
<div class="content">
<div class="paragraph">
<div class="title">Contents</div>
<p>Specification of <strong>all</strong> communication partners (users, IT-systems, &#8230;&#8203;) with explanations of domain specific inputs and outputs or interfaces.
Optionally you can add domain specific formats or communication protocols.</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>All stakeholders should understand which data are exchanged with the environment of the system.</p>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.</p>
</div>
<div class="paragraph">
<p>Alternatively (or additionally) you can use a table.
The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.</p>
</div>
</div>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tbody>
<tr>
<th class="tableblock halign-left valign-top">Entity</th>
<th class="tableblock halign-left valign-top">Input</th>
<th class="tableblock halign-left valign-top">Output</th>
<td class="tableblock halign-left valign-top"><p class="tableblock">Entity</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Input</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Output</p></td>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>User</strong></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">App usage and experience.</p></td>
Expand All @@ -983,10 +1053,23 @@ <h3 id="_technical_context">3.2. Technical Context</h3>
<div class="sidebarblock arc42help">
<div class="content">
<div class="paragraph">
<p>The following diagram represents the general structure of the project, as well as the communication channels between various system components. It shows communication to external sources, as well as communications between the various microsystems.</p>
<div class="title">Contents</div>
<p>Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation which I/O uses which channel.</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.</p>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>E.g. UML deployment diagram describing channels to neighboring systems,
together with a mapping table showing the relationships between channels and input/output.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>The following diagram represents the general structure of the project, as well as the communication channels between various system components. It shows communication to external sources, as well as communications between the various microsystems.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./images/03-deployment-diagram-EN.png" alt="03 deployment diagram EN">
Expand Down Expand Up @@ -1783,7 +1866,46 @@ <h2 id="section-design-decisions">9. Architecture Decisions</h2>
<div class="sectionbody">
<div class="sidebarblock arc42help">
<div class="content">

<div class="paragraph">
<div class="title">Contents</div>
<p>Important, expensive, large scale or risky architecture decisions including rationales.
With "decisions" we mean selecting one alternative based on given criteria.</p>
</div>
<div class="paragraph">
<p>Please use your judgement to decide whether an architectural decision should be documented
here in this central section or whether you better document it locally
(e.g. within the white box template of one building block).</p>
</div>
<div class="paragraph">
<p>Avoid redundancy.
Refer to section 4, where you already captured the most important decisions of your architecture.</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>Stakeholders of your system should be able to comprehend and retrace your decisions.</p>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>Various options:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>ADR (<a href="https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions">Documenting Architecture Decisions</a>) for every important decision</p>
</li>
<li>
<p>List or table, ordered by importance and consequences or:</p>
</li>
<li>
<p>more detailed in form of separate sections per decision</p>
</li>
</ul>
</div>
<div class="paragraph">
<div class="title">Further Information</div>
<p>See <a href="https://docs.arc42.org/section-9/">Architecture Decisions</a> in the arc42 documentation.
There you will find links and examples about ADR.</p>
</div>
</div>
</div>
<table class="tableblock frame-all grid-all stretch">
Expand Down Expand Up @@ -1823,16 +1945,63 @@ <h2 id="section-design-decisions">9. Architecture Decisions</h2>
<div class="sect1">
<h2 id="section-quality-scenarios">10. Quality Requirements</h2>
<div class="sectionbody">
<div class="sidebarblock">
<div class="sidebarblock arc42help">
<div class="content">
<div class="paragraph">
<p>To describe the quality requirements that the game will have, we will use quality scenarios. Quality scenarios describe
the action to be performed by the user or the system (stimulus) in order to generate a response to the interaction.</p>
<div class="title">Content</div>
<p>This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)</p>
</div>
<div class="paragraph">
<p>Here you can also capture quality requirements with lesser priority,
which will not create high risks when they are not fully achieved.</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>Since quality requirements will have a lot of influence on architectural
decisions you should know for every stakeholder what is really important to them,
concrete and measurable.</p>
</div>
<div class="paragraph">
<div class="title">Further Information</div>
<p>See <a href="https://docs.arc42.org/section-10/">Quality Requirements</a> in the arc42 documentation.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>To describe the quality requirements that the game will have, we will use quality scenarios. Quality scenarios describe
the action to be performed by the user or the system (stimulus) in order to generate a response to the interaction.</p>
</div>
<div class="sect2">
<h3 id="_quality_tree">10.1. Quality Tree</h3>
<div class="sidebarblock arc42help">
<div class="content">
<div class="paragraph">
<div class="title">Content</div>
<p>The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>The tree structure with priorities provides an overview for a sometimes large number of quality requirements.</p>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>The quality tree is a high-level overview of the quality goals and requirements:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root</p>
</li>
<li>
<p>a mind map with quality categories as main branches</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In any case the tree should include links to the scenarios of the following section.</p>
</div>
</div>
</div>
<div class="imageblock">
<div class="content">
<img src="./images/QualityTree.png" alt="QualityTree">
Expand All @@ -1841,6 +2010,44 @@ <h3 id="_quality_tree">10.1. Quality Tree</h3>
</div>
<div class="sect2">
<h3 id="_quality_scenarios">10.2. Quality Scenarios</h3>
<div class="sidebarblock arc42help">
<div class="content">
<div class="paragraph">
<div class="title">Contents</div>
<p>Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.</p>
</div>
<div class="paragraph">
<p>These scenarios describe what should happen when a stimulus arrives at the system.</p>
</div>
<div class="paragraph">
<p>For architects, two kinds of scenarios are important:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.</p>
</li>
<li>
<p>Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.</p>
</li>
</ul>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>Scenarios make quality requirements concrete and allow to
more easily measure or decide whether they are fulfilled.</p>
</div>
<div class="paragraph">
<p>Especially when you want to assess your architecture using methods like
ATAM you need to describe your quality goals (from section 1.2)
more precisely down to a level of scenarios that can be discussed and evaluated.</p>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>Tabular or free form text.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>Quality scenarios, also known as use cases, are detailed descriptions of situations in which a user interacts with
a system and describe the expected outcomes along with the conditions of the environment in which the interaction
Expand Down Expand Up @@ -1904,7 +2111,23 @@ <h2 id="section-technical-risks">11. Risks and Technical Debts</h2>
<div class="sidebarblock arc42help">
<div class="content">
<div class="paragraph">
<p>Hola</p>
<div class="title">Contents</div>
<p>A list of identified technical risks or technical debts, ordered by priority</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)</p>
</div>
<div class="paragraph">
<p>This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.</p>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.</p>
</div>
<div class="paragraph">
<div class="title">Further Information</div>
<p>See <a href="https://docs.arc42.org/section-11/">Risks and Technical Debt</a> in the arc42 documentation.</p>
</div>
</div>
</div>
Expand Down Expand Up @@ -1938,7 +2161,38 @@ <h2 id="section-glossary">12. Glossary</h2>
<div class="sectionbody">
<div class="sidebarblock arc42help">
<div class="content">

<div class="paragraph">
<div class="title">Contents</div>
<p>The most important domain and technical terms that your stakeholders use when discussing the system.</p>
</div>
<div class="paragraph">
<p>You can also see the glossary as source for translations if you work in multi-language teams.</p>
</div>
<div class="paragraph">
<div class="title">Motivation</div>
<p>You should clearly define your terms, so that all stakeholders</p>
</div>
<div class="ulist">
<ul>
<li>
<p>have an identical understanding of these terms</p>
</li>
<li>
<p>do not use synonyms and homonyms</p>
</li>
</ul>
</div>
<div class="paragraph">
<div class="title">Form</div>
<p>A table with columns &lt;Term&gt; and &lt;Definition&gt;.</p>
</div>
<div class="paragraph">
<p>Potentially more columns in case you need translations.</p>
</div>
<div class="paragraph">
<div class="title">Further Information</div>
<p>See <a href="https://docs.arc42.org/section-12/">Glossary</a> in the arc42 documentation.</p>
</div>
</div>
</div>
<table class="tableblock frame-all grid-all stretch">
Expand Down

0 comments on commit d59ee76

Please sign in to comment.