Skip to content

Commit

Permalink
Merge pull request #1 from HAW-Rust-SoSe24/docs_update
Browse files Browse the repository at this point in the history
Docs: Adjust, Add a few things & Hide Help Text
  • Loading branch information
AnnsAnns authored May 2, 2024
2 parents afa87e9 + 5d17a3c commit 8983497
Show file tree
Hide file tree
Showing 11 changed files with 82 additions and 123 deletions.
30 changes: 18 additions & 12 deletions docs/src/content/docs/arc42/01. Introduction and Goals.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Introduction and Goals
description: Describes the relevant requirements and the driving forces that software architects and development team must consider.
---

Introduction and Goals
<!-- Introduction and Goals
======================
Describes the relevant requirements and the driving forces that software
Expand All @@ -14,13 +14,18 @@ architects and development team must consider. These include
- quality goals for the architecture
- relevant stakeholders and their expectations
- relevant stakeholders and their expectations -->


Requirements Overview
---------------------

**Contents.**
1. Implement the original CPU instructions
2. Implement the original memory layout
3. Implement a graphical user interface
4. Implement controls

<!-- **Contents.**
Short description of the functional requirements, driving forces,
extract (or abstract) of requirements. Link to (hopefully existing)
Expand All @@ -39,12 +44,14 @@ requirements documents exist this overview should refer to these
documents.
Keep these excerpts as short as possible. Balance readability of this
document with potential redundancy w.r.t to requirements documents.
document with potential redundancy w.r.t to requirements documents. -->

Quality Goals
-------------

**Contents.**
1. The instructions should not deviate from the original

<!-- **Contents.**
The top three (max five) quality goals for the architecture whose
fulfillment is of highest importance to the major stakeholders. We
Expand All @@ -60,11 +67,11 @@ architect do not know how the quality of your work will be judged …
**Form.**
A table with quality goals and concrete scenarios, ordered by priorities
A table with quality goals and concrete scenarios, ordered by priorities -->

Stakeholders
------------

<!--
**Contents.**
Explicit overview of stakeholders of the system, i.e. all person, roles
Expand All @@ -90,9 +97,8 @@ level of detail of your work and its results.
**Form.**
Table with role names, person names, and their expectations with respect
to the architecture and its documentation.
to the architecture and its documentation. -->

| Role/Name | Contact | Expectations |
| ----------- | ------------------------- | ------------------------- |
| Role-1 | Contact-1 | *&lt;Expectation-1*&gt; |
| Role-2 | Contact-2 | *&lt;Expectation-2*&gt; |
| Role/Name | Expectations |
| ----------- | ------------------------- |
| Silke & Korf| Working end result, understandable architecture |
13 changes: 11 additions & 2 deletions docs/src/content/docs/arc42/02. Architecture Constraints.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Architecture Constraints
description: Describes the constraints that software architects must consider.
---

Architecture Constraints
<!-- Architecture Constraints
========================
**Contents.**
Expand All @@ -24,4 +24,13 @@ always be dealt with; they may be negotiable, though.
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)
documentation or naming conventions) -->

| Constraint | Description |
|------------|-------------|
| Deadline | The project must be completed by the end of the semester. |
| Budget | All developers have other classes to attend, this can't take too much of their time away |
| Programming Language | The project must be implemented in Rust. |
| Documentation | The project must be documented well. |
| Testing | The project must be tested well. |
| Every developers must have a good understanding of the project | The project must be implemented in a way that every developer can understand it for the final exam. |
11 changes: 6 additions & 5 deletions docs/src/content/docs/arc42/03. Context and scope.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: System Scope and Context
description: Delimits your system from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.
---

System Scope and Context
<!-- System Scope and Context
========================
**Contents.**
Expand All @@ -28,12 +28,13 @@ Various options:
- Context diagrams
- Lists of communication partners and their interfaces.
- Lists of communication partners and their interfaces. -->


Business Context
----------------

<!--
**Contents.**
Specification of **all** communication partners (users, IT-systems, …)
Expand All @@ -57,12 +58,12 @@ the communication partner, the inputs, and the outputs.
**&lt;Diagram or Table&gt;**
**&lt;optionally: Explanation of external domain interfaces&gt;**
**&lt;optionally: Explanation of external domain interfaces&gt;** -->


Technical Context
-----------------

<!--
**Contents.**
Technical interfaces (channels and transmission media) linking your
Expand All @@ -86,4 +87,4 @@ and input/output.
**&lt;optionally: Explanation of technical interfaces&gt;**
**&lt;Mapping Input/Output to Channels&gt;**
**&lt;Mapping Input/Output to Channels&gt;** -->
10 changes: 8 additions & 2 deletions docs/src/content/docs/arc42/04. Solution Strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Solution Strategy
description: A short summary and explanation of the fundamental decisions and solution strategies, that shape the system’s architecture.
---

Solution Strategy
<!-- Solution Strategy
=================
**Contents.**
Expand Down Expand Up @@ -32,4 +32,10 @@ Keep the explanation of these key decisions short.
Motivate what you have decided and why you decided that way, based upon
your problem statement, the quality goals and key constraints. Refer to
details in the following sections.
details in the following sections. -->

## Decisions

### Bevy as the UI Engine

We decided to use Bevy as the UI engine for the game. Bevy is a game engine built in Rust that is designed to be fast and easy to use. It is a new engine that is still in development, but it should serve our more simple needs well.
15 changes: 8 additions & 7 deletions docs/src/content/docs/arc42/05. Building Block View.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Building Block View
description: Shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, datas structures, …) as well as their dependencies (relationships, associations, …)
---

Building Block View
<!-- Building Block View
===================
**Content.**
Expand Down Expand Up @@ -39,11 +39,11 @@ with black box descriptions of all contained building blocks.
the white box description of selected building blocks of level 1,
together with black box descriptions of their internal building blocks.
**Level 3** zooms into selected building blocks of level 2, and so on.
**Level 3** zooms into selected building blocks of level 2, and so on. -->

Whitebox Overall System
-----------------------

<!--
Here you describe the decomposition of the overall system using the
following white box template. It contains
Expand Down Expand Up @@ -145,11 +145,11 @@ box template:
### &lt;Name interface m&gt;
### &lt;Name interface m&gt; -->

Level 2
-------

<!--
Here you can specify the inner structure of (some) building blocks from
level 1 as white boxes.
Expand All @@ -172,11 +172,12 @@ standardized parts of your system
### White Box *&lt;building block m&gt;*
*&lt;white box template&gt;*
*&lt;white box template&gt;* -->

Level 3
-------

<!--
Here you can specify the inner structure of (some) building blocks from
level 2 as white boxes.
Expand All @@ -195,5 +196,5 @@ Specifies the internal structure of *building block x.1*.
### White Box &lt;\_building block y.1\_&gt;
*&lt;white box template&gt;*
*&lt;white box template&gt;* -->

4 changes: 2 additions & 2 deletions docs/src/content/docs/arc42/06. Runtime View.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Runtime View
description: Describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas; important use cases or features, interactions at critical external interfaces, operation and administration, error and exception scenarios.
---

Runtime View
<!-- Runtime View
============
**Contents.**
Expand Down Expand Up @@ -67,4 +67,4 @@ There are many notations for describing scenarios, e.g.
&lt;Runtime Scenario n&gt;
--------------------------
...
... -->
10 changes: 6 additions & 4 deletions docs/src/content/docs/arc42/07. Deployment View.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Deployment View
description: Describes the technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and the mapping of (software) building blocks to that infrastructure elements.
---

Deployment View
<!-- Deployment View
===============
**Content.**
Expand Down Expand Up @@ -49,11 +49,12 @@ additional deployment diagrams:
- When your (hardware) stakeholders prefer other kinds of diagrams
rather than the deployment diagram, let them use any kind that is
able to show nodes and channels of the infrastructure.
able to show nodes and channels of the infrastructure. -->

Infrastructure Level 1
----------------------

<!--
Describe (usually in a combination of diagrams, tables, and text):
- the distribution of your system to multiple locations, environments,
Expand Down Expand Up @@ -81,13 +82,14 @@ Quality and/or Performance Features
Mapping of Building Blocks to Infrastructure
: *&lt;description of the mapping&gt;*
: *&lt;description of the mapping&gt;* -->



Infrastructure Level 2
----------------------

<!--
Here you can include the internal structure of (some) infrastructure
elements from level 1.
Expand All @@ -105,5 +107,5 @@ Please copy the structure from level 1 for each selected element.
### *&lt;Infrastructure Element n&gt;*
*&lt;diagram + explanation&gt;*
*&lt;diagram + explanation&gt;* -->

3 changes: 2 additions & 1 deletion docs/src/content/docs/arc42/08. Crosscutting Concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ description: Describes the overall, principal regulations and solution ideas tha
Cross-cutting Concepts
======================

<!--
**Content.**
This section describes overall, principal regulations and solution ideas
Expand Down Expand Up @@ -85,4 +86,4 @@ specific topic on this list.
*&lt;Concept n&gt;*
-------------------
*&lt;explanation&gt;*
*&lt;explanation&gt;* -->
5 changes: 4 additions & 1 deletion docs/src/content/docs/arc42/09. Architecture Decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Architecture Decisions
description: Describes the important, expensive, large scale or risky architecture decisions including rationals.
---

<!--
Design Decisions
================
Expand Down Expand Up @@ -33,4 +34,6 @@ Various options:
- more detailed in form of separate sections per decision
- ADR (architecture decision record) for every important decision
- ADR (architecture decision record) for every important decision -->

Is this needed?
Loading

0 comments on commit 8983497

Please sign in to comment.