This is the multi-page printable view of this section. Click here to print.
Docs
- 1: Diagrams-as-Code
- 2: Docs-as-Code
- 3: Documentation Engineering
- 4: Enterprise Architecture Management
1 - Diagrams-as-Code
1.1 - Mermaid
Introduction
Mermaid is a JavaScript-based diagramming and visualization library that enables the creation of diagrams and flowcharts using text descriptions. Mermaid is frequently used in Markdown documents (e.g., in GitHub, GitLab, or Confluence) to visually represent complex relationships.
Advantages of Mermaid:
- Simple integration into Markdown documents.
- No external tools required – diagrams are rendered directly in the browser.
- Supports a wide variety of diagram types.
- Ideal for documentation, presentations, and technical specifications.
Possible Diagrams
Flowchart
Flowcharts visualize processes or workflows. They consist of nodes (steps) and connections (arrows) representing the sequence of steps.
Example:
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Process 1]
B -->|No| D[Process 2]
C --> E[End]
D --> E
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Process 1]
B -->|No| D[Process 2]
C --> E[End]
D --> E
Explanation:
flowchart TD: Defines a flowchart from top to bottom.A[Start]: A node labeled “Start”.-->: Connection between nodes.|Yes|and|No|: Labels for the connections.
Class Diagram
Class diagrams show the structure of classes, their attributes, methods, and relationships to each other.
Example:
classDiagram
class Animal {
-name: String
+eat()
}
class Dog {
+bark()
}
Animal <|-- Dog
classDiagram
class Animal {
-name: String
+eat()
}
class Dog {
+bark()
}
Animal <|-- Dog
Explanation:
classDiagram: Defines a class diagram.AnimalandDog: Classes with attributes (-name) and methods (+eat()).<|--: Inheritance relationship (Dog inherits from Animal).
Sequence Diagram
Sequence diagrams visualize interactions between objects or actors in a chronological sequence.
Example:
sequenceDiagram
Alice->>Bob: Hello!
Bob-->>Alice: Hello back!
sequenceDiagram
Alice->>Bob: Hello!
Bob-->>Alice: Hello back!
Explanation:
sequenceDiagram: Defines a sequence diagram.Alice->>Bob: Message from Alice to Bob.-->>: Response from Bob to Alice.
Entity-Relationship Diagram (ER Diagram)
ER diagrams show the relationships between entities in a database.
Example:
erDiagram
CUSTOMER ||--o{ ORDER : has
CUSTOMER {
int id PK
string name
}
ORDER {
int id PK
date orderDate
}
erDiagram
CUSTOMER ||--o{ ORDER : has
CUSTOMER {
int id PK
string name
}
ORDER {
int id PK
date orderDate
}
Explanation:
erDiagram: Defines an ER diagram.CUSTOMER ||--o{ ORDER: One customer has many orders.PK: Primary key.
State Diagram
State diagrams show the states of a system and the transitions between these states.
Example:
stateDiagram-v2
state s1
state Off
state On
[*] --> Off
Off --> On: Turn On
On --> Off: Turn Off
stateDiagram-v2
state s1
state Off
state On
[*] --> Off
Off --> On: Turn On
On --> Off: Turn Off
Explanation:
stateDiagram-v2: Defines a state diagram.[*]: Start state.Off --> On: Transition from “Off” to “On” via “Turn On”.
Mindmap Diagram
Mindmaps visualize hierarchical ideas or concepts.
Example:
mindmap
root((Topic))
Branch 1
Subtopic 1
Subtopic 2
Branch 2
Subtopic 3
mindmap
root((Topic))
Branch 1
Subtopic 1
Subtopic 2
Branch 2
Subtopic 3
Explanation:
mindmap: Defines a mindmap.root((Topic)): Central topic.- Indentations define the hierarchy.
Requirement Diagram
Requirement diagrams show requirements and their relationships.
Example:
requirementDiagram
requirement Requirement1 {
id: 1
text: "The system must be secure."
}
element System {
type: software
}
System - satisfies -> Requirement1
requirementDiagram
requirement Requirement1 {
id: 1
text: "The system must be secure."
}
element System {
type: software
}
System - satisfies -> Requirement1
Explanation:
requirementDiagram: Defines a requirement diagram.requirement: Defines a requirement.satisfies: Relationship between element and requirement.
Gantt Diagram
Gantt diagrams visualize project plans and timelines.
Example:
gantt
title Project Plan
dateFormat YYYY-MM-DD
section Phase 1
Task 1 :a1, 2024-01-01, 7d
Task 2 :after a1, 3d
gantt
title Project Plan
dateFormat YYYY-MM-DD
section Phase 1
Task 1 :a1, 2024-01-01, 7d
Task 2 :after a1, 3d
Explanation:
gantt: Defines a Gantt diagram.dateFormat: Format for date specifications.Task 1 :a1, 2024-01-01, 7d: Task 1 lasts 7 days starting from January 1, 2024.
Timeline
Timelines show events in chronological order.
Example:
timeline
title Important Events 2024 - 2025
2024 : Event 1
2025 : Event 2
timeline
title Important Events 2024 - 2025
2024 : Event 1
2025 : Event 2
Explanation:
timeline: Defines a timeline.2024 : Event 1: Event in the year 2024.
Further Information
Weblinks
1.2 - PlantUML
Introduction
PlantUML is an open-source tool that enables the generation of diagrams from simple text descriptions. It supports a wide variety of diagram types, both UML-based and non-UML-based. PlantUML is particularly useful for developers, architects, and project managers, as it simplifies the creation and maintenance of diagrams and can be integrated into many development environments.
Possible UML-based Diagrams
Sequence Diagram
Description: A sequence diagram shows the interaction between objects in a specific order. It is frequently used to visualize the flow of messages between objects in a system.
Example in PlantUML:
@startuml
Alice -> Bob: Hello!
Bob --> Alice: Hello back!
@enduml
Explanation:
->shows a message from one object to another.-->shows a response.
Activity Diagrams
Description: Activity diagrams (also known as flowcharts) show the flow of activities and decisions in a process. They are particularly useful for visualizing business processes or algorithms.
Example in PlantUML:
@startuml
start
:Activity 1; :Activity 2;
if (Condition?) then (Yes)
:Activity 3;
else (No)
:Activity 4;
endif
stop
@enduml
Explanation:
startandstopmark the beginning and end of the process.ifandelseshow decisions.
Class Diagram
Description: Class diagrams show the structure of a system through classes, their attributes, methods, and the relationships between the classes.
Example in PlantUML:
@startuml
class Car {
-brand: String
-model: String +drive()
}
class Driver {
-name: String +steer()
}
Car "1" *-- "1" Driver
@enduml
Explanation:
-shows private attributes,+shows public methods.-->shows an association between classes.
Object Diagram
Description: Object diagrams show instances of classes at a specific point in time and their relationships to each other.
Example in PlantUML:
@startuml
object Car1 {
brand = "VW"
model = "Golf"
}
object Driver1 {
name = "Max"
}
Car1 --> Driver1
@enduml
Explanation:
objectdefines an instance of a class.-->shows a relationship between objects.
State Diagram
Description: State diagrams show the various states of an object and the transitions between these states.
Example in PlantUML:
@startuml
[*] --> Off
Off --> On : switch on
On --> Off : switch off
@enduml
Explanation:
[*]shows the start state.-->shows a transition between states.
Possible Non-UML-based Diagrams
Visualization of JSON/YAML Data
Description: PlantUML can visualize JSON or YAML data to better understand the structure and hierarchy of the data.
Example in PlantUML:
@startjson
{
"name": "Max",
"age": 30,
"address": {
"street": "Main Street 1",
"city": "Berlin"
}
}
@endjson
Explanation:
@startjsonand@endjsonenclose the JSON code.
Archimate Diagram
Description: Archimate diagrams are used to model enterprise architectures. They show the relationships between business processes, applications, and technologies.
Example in PlantUML:
@startuml
archimate #Business "Business Process" as bp
archimate #Application "Application" as app
bp --> app
@enduml
Explanation:
archimatedefines an Archimate element.-->shows a relationship between elements.
Gantt Diagram
Description: Gantt diagrams show project plans and the timeline of tasks.
Example in PlantUML:
@startgantt
[Task 1] lasts 5 days
[Task 2] starts at [Task 1]'s end and lasts 3 days
@endgantt
Explanation:
lastsdefines the duration of a task.starts atshows the start of a task relative to another.
Mindmap Diagram
Description: Mindmaps visualize ideas and concepts in a hierarchical structure.
Example in PlantUML:
@startmindmap
* Root
** Branch 1
*** Leaf 1
** Branch 2
@endmindmap
Explanation:
*shows the root node.**and***show child nodes.
Network Diagram
Description: Network diagrams show the structure and connections in a network.
Example in PlantUML:
@startuml
node "Server" as s
node "Client" as c
s -- c
@enduml
Explanation:
nodedefines a node in the network.--shows a connection between nodes.
Work Breakdown Structure (WBS)
Description: A Work Breakdown Structure (WBS) shows the hierarchy and structure of a project.
Example in PlantUML:
@startwbs
* Project
** Phase 1
*** Task 1
*** Task 2
** Phase 2
@endwbs
Explanation:
*shows the main project.**and***show sub-elements.
Further Information
Weblinks
2 - Docs-as-Code
2.1 - Asciidoc
Syntax
Since AsciiDoc is offered as a “complete system,” including both language and interpreter, there is a central syntax. Unlike Markdown, AsciiDoc has no variants or dialects.
Comments
AsciiDoc code can be commented, just like any other source code. This means that comments are not taken into account during the interpretation of the source text (e.g., when converting to PDF). This allows documents or parts of text to be commented on, or notes to be left.
This is arbitrary text in AsciiDoc.
// This line will not be interpreted.
This line will be displayed.
Paragraphs/Lines
AsciiDoc does not require special specifications for line breaks and paragraphs. The text is rendered as it was written. However, it is possible to force a line break using a plus symbol. Alternatively, the attribute [%hardbreaks] can be prepended.
This is line number one.
This is line number two.
And now another paragraph.
This line will be +
hard broken.
[%hardbreaks]
These lines will be
displayed as they are.
Text Formatting
Bold, Italic, Highlight, Code
To display text as bold, italic, or code, there are two possibilities, depending on whether the text to be formatted stands alone or is located in the middle of a text.
A single word can be enclosed in single asterisks, underscores, hashtags, or grave accents.
This text is *bold*.
This text is _italic_.
This text is `code`.
This text is #highlighted#.
If you want to format a part of text in the middle of a sentence, this is achieved by using double asterisks, underscores, hashtags, or grave accents. If this were attempted with single characters, the formatting rule would be ignored.
The "tt" in Mi**tt**ag are bold.
The "tt" in Mi*tt*ag are not bold.
The "tt" in Mi__tt__ag are italic.
The "tt" in Mi_tt_ag are not italic.
The "tt" in Mi``tt``ag are code.
The "tt" in Mi`tt`ag are not code.
The "tt" in Mi##tt##ag are highlighted.
The "tt" in Mi#tt#ag are not highlighted.
Underlined, Strikethrough
To underline or strikethrough text, hashtags with an attribute are used.
This text is [.underline]#underlined#.
This text is [.line-through]#strikethrough#.
Superscript, Subscript, and Smart Quotes
Using superscript and subscript, parts of text can be raised or lowered. For this, the text parts are placed between single carets/circumflexes (superscript) or tildes (subscript).
This is a ~low~point.
This is a ^high^point.
Here is the completed AsciiDoc text with content for the empty chapters (starting from “Links”), based on the official AsciiDoc syntax and common best practices:
Here is the revised version of your AsciiDoc documentation — now with a short, concise explanation for each chapter before the syntax examples come. This keeps it clear, understandable, and useful for beginners.
Links
Explanation:
AsciiDoc supports both external web links and internal references within the document (anchors) as well as links to local files. The syntax is simple and intuitive — ideal for documentation that needs to be linked.
External Links
https://www.asciidoc.org[AsciiDoc Website]
Internal Links (Anchors)
[[section1]]
== First Section
See also <<section1>>.
File Links
link:manual.pdf[Download Manual]
Document Header
Explanation:
The document header contains metadata such as title, author, date, and global attributes. It is optional but recommended for structured documents — especially for PDF or book exports.
= Document Title
Author Name <author@example.com>
:doctype: book
:author: Author Name
:revdate: 2026-02-09
Automatic Table of Contents
Explanation:
A table of contents (TOC) is automatically generated as soon as the attribute :toc: is set. It can be placed on the left, right, or anywhere else — helpful for longer documents.
:toc: left
= Main Title
== Chapter 1
Content...
== Chapter 2
Further content...
Includes
Explanation:
With include::, you can embed external AsciiDoc files or parts of them. Practical for reusable sections (e.g., footnotes, notes, chapters).
include::chapter1.adoc[]
include::../shared/footnotes.adoc[tag=section2]
Lists
Explanation:
AsciiDoc supports bulleted lists (*), numbered lists (.), and definition lists (::). Indentation determines the hierarchy — simple and clearly structured.
Bulleted Lists
* Point 1
* Point 2
* Subpoint
Numbered Lists
. First point
. Second point
.. Subpoint
Definitions
Term::
Definition of the term.
Images
Explanation:
Images are embedded using image::. You can control size, alt text, and scaling. Works in HTML, PDF, and EPUB — depending on the backend.
image::logo.png[Logo, 200, 100]
image::diagram.svg[Diagram, scaledwidth=50%]
Audio
Explanation:
Audio files (e.g., voice messages) can be embedded directly in the document. Useful for tutorials or multimedia documentation.
audio::voicemessage.mp3[Voice Message, autoplay]
Videos
Explanation:
Videos are embedded using video::. You can enable controls like autoplay, controls, or loop — ideal for instructions or presentations.
video::tutorial.mp4[Tutorial, width=640, height=360, autoplay, controls]
Keyboard, Button, Menu Macros
Explanation:
With kbd: and menu:, you can clearly highlight keyboard shortcuts and menu paths — particularly useful in instructions or software documentation.
Keyboard Shortcuts
Press kbd:[Ctrl+C] to copy.
Menu Commands
Go to menu:File[Save As...].
Source Code
Explanation:
Code blocks with syntax highlighting are introduced with [source]. You can specify languages like Python, Bash, or HTML — helpful for developer documentation.
[source,python]
----
def hello():
print("Hello World")
----
Notes, Text Blocks
Explanation:
With NOTE:, TIP:, WARNING:, etc., you can highlight important information. Quotes with ____ are ideal for quotations or excerpts from external sources.
Notes
NOTE: This is important information.
TIP: Here's how to do it faster.
Quotes
____
"This is a quote."
— Author
____
Tables
Explanation:
Tables are defined with |===. Each cell is separated by |. You can control column count, borders, and captions — perfect for comparisons or data.
|===
| Column 1 | Column 2
| Value A | Value B
| Value C | Value D
|===
IDs, Roles, and Options
Explanation:
With [[id]], you set anchors for internal links. With [.role], you can assign CSS classes. With [%option], you control block behavior (e.g., unnumbered).
IDs
[[chapter2]]
== Chapter 2
Roles
[.note]
This text has a role.
Options
[%unnumbered]
== This section has no number.
Attributes and Special Characters
Explanation:
Attributes (:name: value) enable reuse of text or values. Special characters like + or \\ may need to be escaped to avoid being interpreted as formatting.
Attributes
:version: 1.0
The version is {version}.
Special Characters
+ for plus, \\ for backslash, ' for apostrophe.
Bibliography
Explanation:
A bibliography can be created manually or via bibliography::. Useful for scientific or referenced documents.
[bibliography]
== Literature
- Author, Title, Publisher, Year
Footnotes
Explanation:
Footnotes are inserted with footnote:[Text] or [footnote:]. They appear at the end of the document or page — ideal for supplementary information.
This is a sentence with a footnote.footnote:[This is the footnote.]
Another sentence with [footnote:2]Footnote 2[footnote:2].
Conclusion
Advantages
A major advantage of AsciiDoc is certainly its wide range of functions, which even allows complex documents with tables of contents and bibliographies. The include function and possible comments also facilitate handling large amounts of text and many files; collaborative editing is thus also easy. Since AsciiDoc is not just a language but also comes with an application, productive work can be done without much detour. Apart from a text editor for the text files, nothing else is needed.
Disadvantages
AsciiDoc is by far not as widely used as Markdown. Productive tools like note-taking apps, wikis, or static site generators rarely support AsciiDoc, and if they do, usually only via plugins. Those who work a lot with such tools will not get around using Markdown and AsciiDoc in parallel.
Further Information
Literature
Weblinks
-
AsciiDoc (auf Englisch)
-
AsciiDoctor (auf Englisch)
Tools for Using AsciiDoc
Text Editors
Static Site Generators
Transformation Tools
2.2 - Markdown
Markdown is certainly the most widespread simple markup language.
Syntax
Basic Syntax
These are the basic commands that Markdown offers and should fundamentally work in every tool.
Headings
To display headings, one or more hashtags are placed before the heading title, depending on the level.
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Note: It is best to always insert a blank line before a heading, as interpretations may otherwise be incorrect.
Paragraphs/Lines
There are no real notations for line breaks and paragraphs; the text is displayed as written. To support a line break, two spaces can be added at the end of the line, or alternatively, the HTML tag <br> can be used.
First line with two spaces at the end.
And now the next line.
First line with the HTML tag at the end.<br>
And now the next line.
Text Formatting
By default, Markdown offers the ability to display text as bold and/or italic.
To display text in bold, the corresponding text part is written between double stars or underscores.
I also have **bold text**.
I also have __bold text__.
And here is **bold text** in the middle.
To display text in italics, the corresponding text part is written between single stars or underscores.
I also have *italic text*.
I also have _italic text_.
And here is *italic text* in the middle.
Of course, these can also be combined:
To display text in bold and italic, the corresponding text part is written between triple stars or underscores.
I also have ***bold and italic text***.
I also have ___bold and italic text___.
And here is ***bold and italic text*** in the middle.
Blockquotes
To quote text as a block, simply place a “greater than” sign before the line.
> This text is in a blockquote.
If the blockquote is to span multiple lines, the “greater than” sign must be placed at the beginning of each line (including empty lines).
> This text represents the first line in the blockquote.
>
> And here is the next line.
Quotes can also be nested; in this case, an additional “greater than” sign is added for the next level or indentation.
> This text is in a blockquote.
>
>> This text is nested.
Lists
Lists are just as simple and are written directly in the text. If the list goes to another level, this is enabled by indentation (4 spaces or 1 tab).
Ordered List
Ordered lists are generated by simply placing the corresponding number followed by a period before the line.
1. First item
2. Second item
3. Third item
1. first indentation
2. second indentation
4. Fourth item
Unordered List
Unordered lists are generated by simply placing a hyphen before the line.
- First item
- Second item
- Third item
- first indentation
- second indentation
- Fourth item
Links and Images
To display a link, the link text is placed in square brackets, followed by the URL within parentheses.
Ordered lists are generated by simply placing the corresponding number followed by a period before the line.
My favorite search engine is [Swisscows](https://swisscows.com/en).
A title can also be added to the link as a tooltip.
My favorite search engine is [Swisscows](https://swisscows.com/en "The Swiss search engine").
As a shorthand, a URL can also simply be written within angle brackets.
My favorite search engine is <https://swisscows.com/en>.
Extended Syntax
Tables
Tables are defined using vertical bars (|) and hyphens (-). The first line contains the column headers, the second line defines the alignment (optional).
| Left aligned | Centered | Right aligned |
| :----------- | :-----------: | ------------: |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
Note: The number of hyphens in the separator line is arbitrary; only the
:for alignment matters.
Code Blocks
For multi-line code, a code block is created with three backticks (```) or with four spaces per line. Optionally, the language can be specified to activate syntax highlighting.
```python
def hello():
print("Hello, World!")
---
#### Footnotes
Footnotes are inserted in the text with `[^identifier]` and defined at the end of the file with `[^identifier]:`.
```markdown
Here is a text with a footnote.[^1]
[^1]: This is the explanation for the footnote.
Note: Not all Markdown parsers support footnotes – e.g., Hugo requires
goldmarkwith the option enabled.
IDs for Headings
Headings can be provided with an ID to link to them directly (e.g., for tables of contents or anchor links).
## Heading with ID {#my-id}
[Link to heading](#my-id)
Note: In Hugo,
enableInlineShortcodes = truemust be activated in the configuration.
Task Lists
Task lists (checklists) are created with - [ ] for unchecked and - [x] for checked items.
- [x] Task completed
- [ ] To do
- [ ] Do later
Note: Often used in GitHub, GitLab, or note apps like Obsidian.
Strikethrough
Strikethrough text is enclosed with double tildes (~~).
This text is ~~strikethrough~~.
Emojis
Emojis can be inserted directly (e.g., 😊) or with shortcodes like :smile: (depending on the parser).
I'm in a good mood today 😊
Note: In Hugo, emojis must be explicitly activated (
enableEmoji = true).
Highlighting Text
Some parsers (e.g., Hugo with Goldmark) support highlighting with ==:
This text is ==highlighted==.
Note: Not standardized – does not work everywhere.
Sub-/Superscript
Subscript (H₂O) and superscript (x²) are represented with ~ and ^ respectively – but only in some extensions like Pandoc or Hugo with a special parser.
Water is H~2~O.
x^2^ is x squared.
Note: Not part of the CommonMark standard – Works, for example, in Hugo with
goldmarkand the option enabled.
Usage
Markdown does not represent a system of its own but stands purely for an open and freely available syntax. One could compare Markdown to an embeddable scripting language. This is certainly also the reason why so many systems support Markdown and the language is thus so versatile.
Wiki Systems
Wiki systems such as Mediawiki (on which Wikipedia is based), dokuWiki, or integrated wiki functions like those in GitHub or GitLab standardly use Markdown for content management.
Wikis are primarily there to present content, in the Git area documentation for the offered software. Thanks to the simple syntax, these can also be created and managed by non-techies.
Notes
The widely available note apps (or sometimes also called desktop wikis) also rely on Markdown for content management. Often an integrated WYSIWYG editor is provided, but it uses Markdown in the background. There is usually also the possibility to switch to the source text and edit directly there. Examples include Zim, Zettlr, QOwnNotes, and Logseq in the open-source area, or popular variants like Evernote, Obsidian, or Joplin.
Websites
In the area of websites, Markdown appears in two ways. On the one hand, well-known Content Management Systems (such as WordPress and Drupal) often offer plugins/modules to publish content in Markdown. But besides CMS, there are also SSGs, so-called Static Site Generators, such as Hugo or Jekyll. In addition, there are similar systems specialized in technical documentation like MKDocs, Sphinx, or Docusaurus. Here too, all content is created in Markdown and then converted into static websites using a preprocessor, which can then be published.
Presentations/Courses
Besides websites, presentations can also be created with Markdown. However, these are not PowerPoint presentations but are dynamically converted into web elements using preprocessors. Examples include Marp, remarkJS, or Cleaver. Specifically for online courses, the Markdown extension LiaScript is suitable.
Documents
Markdown certainly lacks some functionalities that a word processor like MS Word or LibreOffice Writer can offer, but it is perfectly sufficient for simple documents such as letters.
Conclusion
Advantages
Markdown has a simple and clear syntax and is therefore easy to learn. Markdown documents also have the advantage of being easily readable even in source text. They are thus both machine-readable and human-readable. The latter thanks to the simple and straightforward syntax without overhead. The wide distribution of Markdown and its integration into so many tools also speaks for itself.
Disadvantages
Besides the clear advantages, there is unfortunately also negative news about Markdown.
Markdown is very suitable for articles and notes that are not structured too complexly. If one wants to create more, e.g., large and complex documents, such as entire books, useful functions like a table of contents or the possibility to nest files using “Include” are missing.
Although there is a Markdown standard with CommonMark, the strong distribution has nevertheless led to many “dialects,” as many tools extend the standard syntax with their own commands. As a result, Markdown documents from different systems are not necessarily compatible with each other.
Further Information
Weblinks
Tools for Using Markdown
Desktop Wikis
Text Editors
Static Site Generators
Transformation Tools
3 - Documentation Engineering
Documentation Engineering – Definition, Purpose, and Classification
What is Documentation Engineering?
Documentation Engineering refers to a systematic, engineering-like approach to the planning, creation, structuring, maintenance, and further development of documentation.
The focus is not on individual documents, but on documentation as a designable system:
with clear structures, defined dependencies, roles, tools, and lifecycles.
Documentation Engineering thus treats documentation similarly to software, architectures, or business processes:
as something that must be designed, operated, and continuously improved.
What is Documentation Engineering good for?
Documentation Engineering addresses typical problems of classical documentation:
- Documentation is incomplete or outdated
- Knowledge is tied to specific individuals or scattered across many silos
- Documents are hard to find or contradictory
- Changes are laborious and error-prone
- Documentation grows uncontrollably alongside the organization and system landscape
The approach helps to:
- Maintain an overview of complex matters
- Ensure consistency across many content pieces
- Achieve sustainability during personnel or organizational changes
- Scale documentation adaptively to company size and complexity
- Use documentation as a working tool rather than mere storage
What distinguishes Documentation Engineering from classical documentation?
Classical documentation often focuses on:
- individual documents
- text content
- manual maintenance
- static formats
Documentation Engineering, in contrast, focuses on:
- Structures instead of individual texts
- Relationships instead of isolated content
- Reusability instead of redundancy
- Processes and tools instead of one-off creation
In short:
Classical documentation answers What is being documented?
Documentation Engineering answers How is documentation designed as a system?
Core Principles of Documentation Engineering
Even without a fixed framework, typical foundational principles can be identified:
1. Structure before content
Before content is created, it is clarified:
- what types of information exist
- how they relate to each other
- how deeply they should be documented
2. Separation of content and presentation
Content is maintained independently of the output medium.
Presentation (web, PDF, wiki, presentation) is secondary.
3. Modularity and reusability
Information is prepared so that it can be:
- reused multiple times
- combined context-dependently
- maintained centrally
4. Lifecycle thinking
Documentation has:
- a creation context
- a usage phase
- triggers for changes
- a possible end
Documentation Engineering explicitly accounts for this lifecycle.
How can Documentation Engineering be implemented?
Documentation Engineering is not a single tool, but a combination of:
- mental models
- structural principles
- roles
- processes
- tools
Depending on the context, different implementation approaches are used.
Docs-as-Ecosystems
The term Docs-as-Ecosystems describes documentation as a networked system consisting of:
- content
- metadata
- relationships
- versions
- target audiences
Documentation is thus not understood as a collection of individual files, but as an information landscape that grows alongside the company.
Typical characteristics:
- clear navigation and linking logic
- multiple entry points for different target audiences
- loose coupling instead of monolithic documents
Docs-as-Code
Docs-as-Code transfers proven principles from software development to documentation:
- version control (e.g., Git)
- reviews and approvals
- automated builds
- traceable changes
Advantages:
- transparency in changes
- better collaboration
- reduced dependency on individuals
- better integration into existing development processes
Docs-as-Code is not an end in itself, but an enabler for sustainable documentation.
Diagrams-as-Code
Diagrams-as-Code extends the approach to graphical content:
- diagrams are described textually
- they are versionable
- they can be generated automatically
Examples:
- architecture diagrams
- process illustrations
- dependency overviews
The advantage lies not primarily in the technology, but in:
- consistency between text and graphics
- better maintainability
- reduced media discontinuity
Roles and Responsibilities
Documentation Engineering requires clear responsibilities, for example:
- content responsibility (What is correct?)
- structural responsibility (Where does something belong?)
- technical responsibility (How is it generated?)
These roles do not necessarily have to be full-time positions, but should be clearly designated.
When is Documentation Engineering worthwhile?
The approach is particularly useful when:
- organizations grow or change
- systems and processes become more complex
- knowledge can no longer be shared informally
- documentation gains strategic importance
- regulatory or organizational requirements increase
For very small, stable environments, classical documentation may suffice.
However, with increasing complexity, the benefits of a systematic approach rise significantly.
Conclusion
Documentation Engineering is not a new buzzword, but the consistent application of engineering thinking to documentation.
It helps to:
- make documentation plannable
- manage complexity
- keep knowledge sustainably available
Not through more documents, but through better structure, clear responsibilities, and suitable tools.
Good documentation does not happen by chance –
it is the result of conscious design.
Further Information
Literature
Weblinks
4 - Enterprise Architecture Management
Enterprise Architecture Management (EAM) is a strategic management tool that helps organizations align their IT infrastructure with their business processes. It creates transparency regarding the organization’s architecture and enables the targeted evolution of business models, applications, and technologies.
Levels
Business Level
The business level describes the strategic objectives, business processes, organizational units, and roles of the enterprise. It forms the foundation for all other levels.
- Objectives: Strategic alignment, value creation, customer benefit
- Processes: End-to-end business processes (e.g., order processing, customer service)
- Organization: Structure, roles, responsibilities
- Information: Business data, key performance indicators, regulations
Example: A banking business describes the processes “submit loan application”, “creditworthiness check”, “contract conclusion”.
Application Level
The application level describes the software systems and applications used to support business processes.
- Applications: ERP systems, CRM tools, portals, microservices
- Integrations: Interfaces between systems (APIs, middleware)
- Data flows: How data is exchanged between applications
- Functional dependencies: Which application supports which business processes
Example: SAP ERP supports accounting, Salesforce CRM supports sales.
Technology Level
The technology level describes the IT infrastructure on which the applications run.
- Hardware: Servers, data centers, end-user devices
- Software: Operating systems, databases, middleware
- Networks: LAN, WAN, cloud infrastructure
- Security & Compliance: Access control, encryption, backup
Example: Virtualized environment with Kubernetes, PostgreSQL database, Azure cloud hosting.
Frameworks
TOGAF (The Open Group Architecture Framework)
TOGAF is the most widely used EAM framework worldwide. It provides a structured approach for developing and managing enterprise architectures.
- ADM (Architecture Development Method): 8-phase process for architecture development
- Content Framework: Templates for architecture artifacts (e.g., views, models)
- Enterprise Continuum: Classification of architectures (from generic to specific)
- TOGAF Standard: Open, extensible, maintained by The Open Group
Advantages: Broad acceptance, well-documented, scalable
Disadvantages: Complex, high learning effort
Zachman Framework
The Zachman Framework is a classification schema that structures architecture information along two dimensions: Perspectives (Who? – from CEO to technician) and Aspects (What? Where? How? When? Why?).
- 6 Perspectives: Planner, Owner, Designer, Builder, Subcontractor, Enterprise
- 6 Aspects: Data, Function, Network, People, Time, Motivation
- 6x6 Matrix: Each cell contains a specific architecture artifact
Advantages: Highly structured, good for documentation and coverage
Disadvantages: No process, no implementation guidance
DYNAMAP (Dynamic Architecture Management)
DYNAMAP is a modern, agile EAM framework specifically designed for digital transformation and dynamic organizations.
- Focus on agility: Rapid adaptation to market and technology changes
- Model-driven architecture: Use of models for automation and simulation
- Integration capability: Links EAM with DevOps, cloud, and AI
- Value orientation: Emphasizes the business value of each architecture component
Advantages: Flexible, digitally oriented, suitable for cloud and platform strategies
Disadvantages: Less established, less standardization
Further Information
Literature
Here some books, I read about Enterprise Architecture and can highly recommend:
Weblinks
Some Links to and around EAM Frameworks:
-
Dynamap SI Framework d’architecture d’entreprise (in french)
Tools for Implementing EAM
There are plenty of software products on the market, to manage your architectures with. I am concentrating on freely available Open Source Systems, you can download and use instantly: