Skip to content

arc42-requirements.adoc

Latest commit

 

History

History
202 lines (128 loc) · 6.03 KB

arc42-requirements.adoc

File metadata and controls

202 lines (128 loc) · 6.03 KB

arc42 Template Requirements

Table of Contents
Note

Within the following text, the "arc42 template" shall be abbreviated arc42

1. Kind of Requirements

Goals:

the fundamentals
Usage:

Stakeholders and their perspective on arc42.
Formats:

Technische Formate, wie MS-Word (docx), PDF, HTML oder andere.
Toolchains:

Tools und Skripte, die arc42 anwenden oder Required Formats/Required Versions erzeugen (z. B. Groovy, Shell, Pandoc)
Versions:

Content versions, e.g. the pure structure, with help content, with examples etc. Versions can be available in various Required Formats.

2. Goals

arc42 is well-suited for software architecture documentation and communication. It is free, both for commercial or open-source projects or systems.

arc42 shall be:

  1. Agnostic towards

    1. development process, arc42 can be used in iterative, strict, formal or informal processes

    2. applied technologies of the system (programming languages, frameworks, operating systems)

    3. system domain

    4. kind of system (i.e. interactive, batch, server/backend, mobile, client/server etc.)

    5. system size, arc42 shall support small to medium systems without modification (up to approx 1 million LOC)

    6. system lifecycle phase: it can be used a-priori and a-posteriori for planning, designing or describing systems.

  2. Easily usable. It shall

    1. contain clear and helpful documentation

    2. provide various examples

    3. be available in various

      • formats (e.g. MS-Word ©, pdf, Confluence ©, etc.)

      • versions (e.g. without help, with help included, with examples included etc.)

      • languages, at least English and German

    4. have low requirements to use in the supported toolchains

  3. Flexible

    1. Users (software architects and developers) can adapt and modify arc42 towards their needs.

    2. arc42 can be used with different toolchains.

2.1. Non-Goals

arc42 does not

  • address safety critical systems

  • replace requirements documentation

  • replace formal technical documentation

3. Usage Requirements

3.1. Users and Roles

User

works on a software system, needs to communicate or document architectural aspects (decisions, structures, concepts, requirements etc) of this system.
Contributor

Unterstützt und verbessert template formats, Required Versions, toolchains und/oder Inhalte. Meldet Fehler oder trägt zu Übersetzungen bei.
Founders

Peter Hruschka and Gernot Starke ensure conceptual integrity of the arc42 ecosystem.

3.2. Use Cases

  1. Document: use arc42 to document or communicate a software architecture. This use-case is supported by the available output formats (e.g. docx ©, html, asciidoc)

  2. Maintain: work on the arc42 ecosystem by either

4. Required Formats

4.1. Output Formats

Output formats are used to document existing or planned software systems with the documentation use-case.

arc42 shall support the following output formats:

  1. Microsoft © Word docx format, single file, including

    • table-of-contents

    • header and footer, optionally containing logo

  2. Confluence © format, providing the complete template as space

    • supporting Confluence versions from 3.x up to the latest versions.

  3. AsciiDoctor format (modularized), together with build-system to generate/compile results into html/pdf.

  4. html format, especially the versions including help text and samples

  5. pdf format, restricted to version including help text and samples

4.2. Maintenance Format

  1. Content and structure of arc42 shall be maintained in AsciiDoc.

    • All required output formats shall be generated from this.

Maintenance format shall strive for low redundancy and follow the DRY-principle.

5. Supported Toolchains

  1. Word © or similar text processors, combined with any graphical tool for diagrams.

  2. UML modeling tool, either for diagrams-only or for the complete documentation.

  3. Wikis (e.g. Confluence ©), combined with any graphical tool for diagrams.

  4. Text-based formats (like AsciiDoctor), combined with any graphical tool for diagrams.

For all toolchains, requirements for its application shall be kept low.

6. Required Versions

arc42 shall be supplied in the following versions:

  1. Skeleton version, containing

    • all headers

    • appropriate title-page with formal section (name-of-system, authors etc.)

    • table-of-contents

    • plain structure without help text or samples

    • placeholders for substructures, like black- and whitebox templates

    • empty tables, e.g. for stakeholder, quality-goals, external interfaces etc.

  2. With-Help version, containing the complete skeleton, plus

    • help texts for all chapters and sections

    • explanations

  3. Multiple samples version, containing the complete skeleton, plus example diagrams, tables for every chapter and section.

7. Open Source Requirements

  • arc42 is free and open-source, under a liberal Creative-Commons Sharealike license. It can be used in arbitrary projects for arbitrary systems without any fees or restrictions. Please note - there is no guarantee!

  • It is hosted and maintained on GitHub.

8. Technische Rahmenbedingungen

  • Die Generierung der Formate soll so weit wie möglich automatisiert sein

  • Der Build der Ausgabeformate erfolgt mit Groovy-Skripten und Shell (z. B. build-arc42.sh)

  • Weitere Tools (z. B. Pandoc) werden automatisiert installiert und genutzt