Häufig gestelle Fragen (FAQ)

An dieser Stelle möchten wir typische Fragen rund um arc42 beantworten. Falls Sie noch weitere Fragen haben: Wir nehmen die gerne hier auf!
  • Allgemeines
  • What is Software-Architecture?
    The term „architecture“ comprises software and system architecture. It consists of all structures, components, their interfaces and relationships, which together solve the requirements of the system.

    The focus of *architecture* is mainly on achieving non-functional requirements, like maintainability, flexibility and understandability of the whole system, plus support for all functional requirements as well.

    Architecture describes and prescribes the „solution“ to the requirements and, therefore, both describes and guides its implementation. Architecture is an abstraction of sourcecode artifacts and does therefore not describe or prescribe every implementation detail (but the architecturaly relevant ones!).

    The term *software design* can be used to describe implementation details: design = architecture-in-the-small. In our terminology, design is concerned with the internal structure of the lowest-level building blocks. The design of those lower-level building blocks is usually delegated to single developers, they design and develop the code-structure for these building blocks.


    Zurück zum Seitenanfang
  • Welche Anforderungen gelten für Architekturdokumentation?
    These requirements are quality goals, that means achieving them means effecting compromises: Many quality goals negatively affect each other, so that a global optimization is rather difficult. For exam-ple, accuracy and up-to-dateness of any documentation has negative impact on maintenance cost (as it takes more effort to keep the document current).

    The most important quality goals for architecture documentation are:

    * Maintainability
    * Understandability
    * Accuracy
    * Up-To-Dateness
    * Transparency
    * Stakeholder-Orientation

    ## Efficiently Maintainable
    Due to significant maintenance costs associated with large-scale documentation, architecture documentation aims at keeping this effort in balance with understandability, accuracy and up-to-dateness.

    Maintainability of documentation is affected by (at least) the following factors:

    * Amount of documentation (shorter docu is easier to maintain)
    * Redundancy (repeating information sometimes helps readers to avoid jumping around in docu-ments, but increases maintencance effort)
    * Established standard structure: See section 2.2 on understandability.
    * Tools used: Appropriate tool support can significantly reduce overhead.

    The following steps shall be taken to support maintainability:

    * Limit the amount of details (e.g. do not duplicate information that can be easily taken from sour-cecode), especially:
    * Architecture documentation is no replacement for inline code documentation, but shall be supported by a best-practice approach in sourcecode documentation.
    * Only „architecturally relevant“ details shall be included.
    * Stick to the established structure, so the „location“ of documentation changes are simple to de-termin.

    ## Easily Understandable
    A contracting entity needs to keep a thorough understanding of the architectural structure of , over regular releases
    Understandability of documentation is affected by (at least) the following factors:

    * Ease of Navigation & Retrievability: These are achieved by
    * relying on established, standardized and well-documented structure, so that both readers and writers know in advance where to find or file certain information (e.g. runtime scenar-ios are always documented in chapter 5).
    * Keeping an up-to-date index of keywords and topics, for quick retrieval of information (supported by a project or system glossary).
    * Clarity & Style – both of which are subjective matters.
    * Absence of surprises to readers. For example, the reader shall find every piece of information at exactly the location where it’s expected.

    ## Accurate and Up-To-Date
    Information contained within the architecture documentation has to be both accurate in the sense of “cor-rect”, so that stakeholders (developers, system- and software-architects, testers etc.) can rely on this information.
    Accurateness of documentation is affected by (at least) the following factors:

    * Every fact given in the documentation is currently correct. All changes in the system shall be re-flected in the documentation in a timely manner (when the change occurs). Every change has to be documented not later than release-time.
    * All important facts are given in the documentation. For architecture that means „completeness“ without „exhaustiveness“. See „Maintanability“, section 2.1.
    * Missing information is marked as such. When crucial information is missing, both reasons and time of remedy shall be given.

    Accurate with respect to Modifications, Changes and Releases
    Changes in the system (in its requirements, architecture and implementation) shall be reflected in the respective documentation. There shall be an change history, so that changes can be tracked with appro-priate effort (this is a tradeoff between accuracy and maintainance-costs).

    ## Transparency
    A contracting organisation shall be able to really understand structure and implementation of , even in an outsourced development model, with an appropriate audit effort . It shall audit every release to acknowledge that

    * The required changes have been incorporated, both functional and nonfunctional. This can be done by acceptance testing.
    * The system structure (its architecture) has been modified appropriately: Only those parts of the system have been modified that really needed modification due to the current requirements.
    * The implementation changed according to the the changed architecture. This could be done by inspecting sourcecode artifacts or calculating sourcecode metrics.

    In particular shall a contracting organisation be able to detect inappropriate or unsuitable changes in both architecture and implementation with low (appropriate, see footnote 2) effort.

    A subgoal of transparency is traceability: It shall be possible to trace requirements into the respective solution decisions: Where and how did a specific requirement affect the architecture and implementation?
    Traceability in architecture documentation is achieved by transparency and adherence to corresponding acceptance criteria (especially those described in the architecture criteria catalogue).

    ## You Only Know it’s “Good Enough” when your readers tell you so!
    Readers of architecture documentation shall regularly be questioned for improvement suggestions and the perceived usefulness of the documentation, in order to reflect the documentation maintenance in-vestments.


    Zurück zum Seitenanfang
  • Wie soll ich meine Software-Architektur dokumentieren?
    Dafür haben wir das arc42-Template geschaffen: Es stellt Ihnen eine erprobte (Gliederungs-)Struktur bereit, in der Sie sämtliche praktisch relevanten Informationen rund um Ihre Software- oder Systemarchitektur abbilden können.

    Füllen SIe während der Konstruktion und Entwicklung Ihrer Architektur immer die jeweiligen Abschnitte des Templates.

    Zurück zum Seitenanfang
  • Wie und wo kann ich mehr über Software-Architektur lernen? Soll ich Kurse besuchen, Bücher lesen, Kollegen fragen?
    Software-Architekten benötigen fundierte Erfahrung in Technologien, d.h. Sie müssen Software entwicklen ("programmieren") können. Also nicht nur theoretisch wissen, sondern es praktisch gemacht haben. Auf dieser Grundlage (die Sie sicherlich einige Jahre beschäftigen wird) können Sie zu Software- oder Systemarchitekt werden:

    Erarbeiten Sie Methodenwissen.
    Anschliessend empfehlen wir Ihnen, verstärkt Wert auf methodisches Wissen zu legen. Lesen Sie einige Architektur- und Pattern-Bücher und versuchen Sie, dieses Wissen in Ihren eigenen Projekten (angemessen) anzuwenden.
    Dazu können Sie sicherlich auch Kurse besuchen (hhm - wir empfehlen Ihnen natürlich unsere eigenen...) und Bücher lesen - aber das ergänzt lediglich Ihre Praxiserfahrung.

    Lernen und üben Sie (mündlich und schriftlich) zu kommunizieren.
    Diskutieren Sie mit (erfahrenen!) KollegInnen über Entwürfe und Entwurfsentscheidungen. Stellen Sie Ihre eigenen Entwürfe und Architekturen mal Unbeteiligten vor und holen gezielt Feedback dazu ein!

    Schärfen Sie Ihre Rolle in Projekten
    Der iSAQB hat einen Lehrplan für Software-Architekten veröffentlicht, der das Rollenbild und die Aufgaben von Software-Architekten ausführlich beschreibt. Vergleichen Sie diesen Lehrplan mit Ihrem eigenen Tätigkeitsprofil sowie Ihren persönlichen Fähigkeiten. Arbeiten Sie gezielt an den Unterschieden!! Lernen und üben Sie die Aufgaben, in denen Sie sich weniger gut fühlen!!


    Zurück zum Seitenanfang
  • Fragen zum Template
  • Im Template fehlen die Erläuterungen! Ich sehe nur die Überschriften.
    Sie müssen in Word den "verborgenen Text" einschalten. Hier eine einfache Möglichkeit:

    In der Menüleiste das "Paragraph"-Zeichen klicken - dann sollten Sie den blauen Erläuterungstext sehen!

    hidden-text-in-word Zurück zum Seitenanfang
  • Was ist ein Baustein?
    Die Antwort in 3 Sekunden:
    Ein Baustein (der statischen Bausteinsicht) ist eine Abstraktion von Sourcecode.

    Die Antwort in 60 Sekunden:
    A somewhat longer explanation of building blocks - which gives you something to thing about (hence 60 seconds):
    A building block represents every piece of software which you can either buy, get for free
    (e.g. open source) or have to implement yourself.

    Now comes your part: Think about the parts of your system, or all the pieces of software that makes up your system. Think about subsystems, layers, packages, libraries and all that stuff. In any reasonably large system there are quite a lot of such pieces - we call those building blocks.

    Die ausführliche Antwort (leider englisch - aber Sie verstehen das schon...)
    Building blocks make up the static structure of a software system. They come in different flavours, either blackboxes or whiteboxes. For our purpose of system description we structure building blocks hierarchically.
    On any detail- or abstraction level, your subject-of-interest is a whitebox consisting of a number of blackboxes.
    How do building blocks and black/whiteboxes relate to each other: Building blocks are either black- or whiteboxes, depending on what you (yep, you, dear reader) and the architect of your system want to express.
    Building blocks are all those     things you need to implement your system. See figure 1 for an overview - the explanation follows below.


    Figure 1: Metamodel of Building Blocks

    Every building block shall have an interface, describing everything the building block needs (input-interfaces) and produces (output-interfaces). Furthermore, as you've already read in the previous parts of this howto, it desperately needs the following information:

    • Purpose and responsability
    • location: Where can you find the artifacts (documents, source-code, files) for this building block? In simple cases it's just a filename.
    • variability: In what respects is this building block variable? Is it useable in other contexts, what kind of flexibility does it provide?
    • open issues: Anything not ready yet? Not though about? Risky?
    • fulfilled requirements: If you need traceability, here's the place to go...

    • Programming constructs, like classes. It should be obvious that such constructs consist of of source code.
    • Packages, grouping an arbitrary number of programming constructs. Packages are a kind of namespaces or loose-groupings of building blocks. For example, a layer within your system can be regarded as a package, grouping other building blocks (namely the constituents of this layer).
    • Configurations, defining behaviour or interfaces to existing pieces of software. Examples include
      • Springframework configuration files, describing associations between classes which will be instantiated at runtime by the Spring dependency injection engine.
      • Hibernate mapping files, describing details of object-relational mapping,
      • stylesheet or user-interface-description files (e.g. css, xul, zul), describing layout, color, fonts etc of user interface components
    • Libraries or frameworks, which you can buy, rent or otherwise get from anywhere. Examples:
      • user interface frameworks like Apache-Wicket, ZK, Google-Web-Toolkit to support implementation of user interface programming
      • persistence and OR-mapping frameworks like Hibernate
      • dependency injection frameworks like Spring or Google-Guice
      • libraries like PGP (pretty-good-privacy for encryption), ogg-vorbis (mp3 encoding), open-SAML (open-source security-token handling), Mule (open-source enterprise service bus)

    Zurück zum Seitenanfang
  • Fragen zum Vorgehen / zum Prozess
  • Wie arbeite ich mit einem Team an arc42?
    Das hängt wesentlich von Ihren Werkzeugen ab. Wir haben gute Erfahrungen mit folgenden Tools gesammelt:
    • Wiki (insbesondere TWiki und MediaWiki): Hier ist die Teamfähigkeit ja in die Werkzeuge "eingebaut". Kritisch hierbei ist die Integration grafischer Informationen. Die meisten Modellierungs- oder Zeichenwerkzeuge können Diagramme als jpg oder png-Dateien exportieren, die Sie anschliessend ins Wiki hochladen können - umständlich aber machbar.
    • MagicDraw (tm): Teamfähig beispielsweise über die Versionierung der Modelldateien (einfach) oder das TeamServer-Produkt (teurer). Erlaubt einen automatisierten Export von Diagrammen per ant- oder maven-build, damit auch eine automatisierbare Integration in Wikis.
    • Enterprise-Architect (tm): Teamfähig über Subversion-Integration (für größere Teams) oder gemeinsamen Zugriff auf die EAP-Datei (kleinere Teams).
    Allgemein gilt: Teamarbeit benötigt Abstimmung und (mindestens einen ) "Kümmerer", der die gemeinsam bearbeiteten Artefakte oder Dokumente prüft und eventuelle Konflikte auflöst.
    Zurück zum Seitenanfang
  • Fragen zu Werkzeugen
  • Welche Werkzeuge empfehlen Sie?
    Grundsätzlich stehen wir Werkzeugen, Produkten und Herstellern völlig neutral gegenüber, weil wir als Berater unabhängig bleiben möchten!

    Wir empfehlen keine Produkte oder Hersteller, weil die Auswahlkriterien dazu immer vom organisations- oder projektspezifischen Kontext abhängen. Was für ein System oder Team gut passt, kann für ein anderes Team kontraproduktiv sein!

    Andererseits haben wir mit eine Reihe von Werkzeugen unsere persönlichen Erfahrungen gesammelt - die wir Ihnen natürlich auch gerne weitergeben. Hier ein kurzer Extrakt:

    * Mit praktisch jeder beliebigen Werkzeugkette können SIe mit arc42 produktiv arbeiten - alleine oder in Teams. Es hängt (fast) nur von Organisation und Motivation des Teams ab, ob das gut oder besser funktioniert!
    * Die Bandbreite geeigneter Tools reicht von (meist UML-basierten) Modellierungswerkzeugen über Wikis bis hin zu Textverarbeitung. Mit allen diesen Werkzeugklassen haben wir ausgezeichnete, produktive und praxistaugliche Architekturen entwickelt und dokumentiert!
    * Teamfähigkeit der Tools wird insbesondere für grössere Teams schnell z Zurück zum Seitenanfang
  • Wie setzen Sie das Tool "Enterprise-Architect (tm)" von SPARX Systems für arc42 ein?
    SPARX beschreibt das in der Dokumentation zum Enterprise-Architect recht ausführlich.

    In Teams kleiner 4-5 Personen können Sie gemeinsam auf die EAP-Datei zugreifen - für größere Teams empfehlen wir Ihnen eine "richtige" Versionsverwaltung (etwa Subversion). Stand Januar 2011 unterstützt EA weder Mercurial, Git oder andere DVCS.

    Exportieren Sie regelmässig Ihre gesamte Modellstruktur als EAB-Datei (und versionieren diese).
    Speichern Sie regelmässig, insbesondere nach umfangreichen Modelländerungen, auch die EAP-Datei als Sicherungskopie.

    Ein einfaches arc42-Template für den EA finden Sie bei unseren Downloads. Zurück zum Seitenanfang