Context card
Context cards
Short, self-contained explanations of the technical contexts behind the news: one question, a direct answer, the key points and the glossary terms it builds on. In US English, British English and German.
How to read a context cardContext cardTransitional topic
Cognitive load and split attention: why figures, labels and text belong together
What does cognitive load theory say about combining figures and text in instructions, and what follows for technical documentation?
Cognitive load theory: separating figure and text that belong together costs working memory. Put labels on the figure and text next to what it explains.
Symbol · Safety information readability · Usability · DITA task · Instructions for use (IFU) · Safety sign
Read the cardContext cardTransitional topic
Mental models and concept information: why readers need to know how it works before they act
How does research on mental models support placing concept information before task information in technical documentation?
Readers act on a mental model built from the system image, documentation included. Concept information before tasks helps them predict and recover.
Mental model · DITA concept · DITA task · Human-machine interface (HMI) · Instructions for use (IFU) · Operating mode · Mental model (thinking tool)
Read the cardContext cardTransitional topic
Human error types and troubleshooting: from slips, lapses and mistakes to recovery information
How do the error types of James Reason and Jens Rasmussen's skill-, rule- and knowledge-based behavior help design troubleshooting and recovery information?
Slips, lapses and mistakes need different help: design against slips, checklists against lapses, symptom-cause-remedy tables and system models for mistakes.
Human error · Troubleshooting · DITA troubleshooting topic · Reasonably foreseeable misuse · Risk assessment · Alarm management · Mental model
Read the cardContext cardTransitional topic
Cognitive psychology in technical communication: theory, application and the bridges between them
What is the difference between cognitive psychology as theory and its application in documentation, and how do the two fit together?
Theory describes how readers perceive, remember and decide; application turns it into documentation practice. Bridges make each step visible and checkable.
Mental model · Human error · Warning message · Safety information usability · Usability · Risk assessment · Instructions for use (IFU) · DITA concept · DITA task
Read the cardContext cardTransitional topic
Attention and warning placement: from selective attention and habituation to where warnings go
What does research on attention and warnings say about where and how warnings should be placed in instructions?
A warning works only if noticed, read, understood and acted on. Place it right before the step with the hazard, and keep warnings rare enough to stay seen.
Warning message · Safety information usability · Safety information readability · Safety sign · Warning (HMI message) · Alarm flooding · Risk assessment · Residual risk
Read the cardContext cardTransitional topic
Working memory and procedure steps: why "seven plus or minus two" is the wrong rule
Does working memory research justify a fixed maximum number of steps in a procedure, such as seven plus or minus two?
Miller's 1956 paper set no step limit; Cowan puts working memory at about four chunks. Steps stay on the page, so design each step, not the step count.
DITA task · Instructions for use (IFU) · Usability · Safety information usability · Mental model
Read the cardContext cardTransitional topic
How first principles thinking evolved: an adaptation of many adaptations
Where does first principles thinking come from, and how has it changed on its way to technical writing?
First principles thinking runs from Aristotle via Euclid, Descartes, Boyd and Musk to mental models; its version for technical writers is one more adaptation.
First principles thinking · First principle (philosophy) · Socratic questioning · Axiomatic method · Analysis and synthesis (method) · Cartesian method · First-principles calculation · Destruction and creation (John Boyd) · Reasoning by analogy · Mental model · Latticework of mental models · Five whys · Risk assessment · Assumption (systems engineering)
Read the cardContext card
Documenting foreseeable misuse without making it an option
How do instructions describe reasonably foreseeable misuse without presenting it as a way to use the product?
Foreseeable misuse is stated as a clear boundary with its reason, kept apart from intended use and procedures, never written like an operating step.
Reasonably foreseeable misuse · Intended use · Residual risk · Risk assessment · Information for use · Machinery Regulation (EU) 2023/1230 · ISO 12100 · Warning message
Read the cardContext card
Operating modes in technical documentation
Why do operating modes change what the documentation of a machine has to say?
Each operating mode changes who works where, which safeguards act and which hazards remain, so each mode needs its own documentation decisions.
Operating mode · Operating-mode management · Residual risk · Reasonably foreseeable misuse · Safeguard · Enabling device · Lockout/tagout (LOTO) · Personal protective equipment (PPE) · Qualified person · Machinery Regulation (EU) 2023/1230 · ISO 12100
Read the cardContext card
Where a warning belongs: safety chapter or before the task
Should a warning go into the safety chapter or directly before the step it concerns?
General safety information goes into the safety chapter; a warning about a hazard in a specific action belongs directly before that action.
Warning message · Safety chapter · Residual risk · Risk assessment · Information for use · DITA hazard statement · Three-step method · Safety information usability
Read the cardContext card
Instructions for use: one manual or a set of information products?
Do "instructions for use" mean one user manual or a collection of documents?
Instructions for use can be one manual or a set of information products for several audiences; the set is handed over and also kept in the technical file.
Instructions for use (IFU) · Information for use · Operating manual · Maintenance manual · Technical file · Labeling and instructions for use (MDR and IVDR)
Read the cardContext card
Betriebsanweisung: one German word, many operator documents
What is a Betriebsanweisung, and how does it differ from the manufacturer’s operating manual?
A Betriebsanweisung is the employer’s binding instruction to its staff, not the manufacturer’s operating manual. Companies use the word for many documents.
Ordinance on Industrial Safety and Health (BetrSichV) · Ordinance on Hazardous Substances (GefStoffV) · Operating manual · Instructions for use (IFU) · Personal protective equipment (PPE) · Lockout/tagout (LOTO)
Read the cardContext card
Task analysis across the documentation disciplines
Who uses task analysis, and which documents does it feed?
Safety, regulatory, quality, R&D, technical writing, roll-out and operators all use task analysis — for different documents with different audiences.
Risk assessment · ISO 12100 · IEC 62366-1 · Training needs analysis · Quality documentation · Product lifecycle management (PLM)
Read the cardContext card
Task analysis: one task, three lenses
Is task analysis one method, or are technical, collaborative and cognitive task analysis different things?
Hierarchical, team and cognitive task analysis look at the same task: its steps and plans, its handovers between roles, and the thinking behind it.
Usability · DITA task · Task allocation · Human error · RACI matrix · Training needs analysis
Read the cardContext card
Internal and external technical documentation: what "external" really means
Does "external documentation" mean documentation that is published?
"External" documentation leaves the manufacturer; it is not necessarily public. Function, audience, owner and access decide what a document is.
Technical documentation · Technical file · Information for use · Instructions for use (IFU) · Operating manual · Machinery Regulation (EU) 2023/1230
Read the cardContext card
CRA product categories: default, important and critical
Which CRA products need a notified body, and how many products fall into the stricter categories?
Most CRA products are in the default category with self-assessment; Annex III and IV list the important and critical exceptions.
Cyber Resilience Act (CRA) · Conformity assessment · Notified body (MDR and IVDR) · Harmonized standard · Presumption of conformity · Declaration of Conformity · CE marking
Read the cardContext card
The Radio Equipment Directive: when sector law absorbs aspect requirements
Why does the cybersecurity part of the Radio Equipment Directive create parallel compliance paths?
RED is sector law that also carries aspect requirements; its cybersecurity part duplicated the CRA until the repeal effective December 11, 2027.
Cyber Resilience Act (CRA) · Low Voltage Directive · Electromagnetic compatibility (EMC) · Harmonized standard · Presumption of conformity · CE marking
Read the cardContext card
Machinery Regulation and CRA: coupled through standards, not cross-references
Why can the Machinery Regulation and the Cyber Resilience Act not simply refer to each other?
MR sets safety objectives, the CRA cybersecurity objectives; scopes differ, so consistency comes from standards, not direct legal cross-references.
Machinery Regulation (EU) 2023/1230 · Cyber Resilience Act (CRA) · Harmonized standard · Safety-security convergence · Safety-security interface · IEC 62443 · Presumption of conformity
Read the cardContext card
EN 50742: safety-related security levels and IEC 62443 working together
Is EN 50742 a sign that legislators misunderstand technicalities, and do its SRSLs contradict IEC 62443?
EN 50742 is a CENELEC standard, not law: SRSLs set a safety function's protection need, IEC 62443 supplies the controls; they combine.
Machinery Regulation (EU) 2023/1230 · IEC 62443 · Security level (SL) · Safety-security convergence · Tamper resistance · Harmonized standard · Presumption of conformity · Risk assessment
Read the cardContext card
The SBOM under BSI TR-03183-2: an inventory, not a vulnerability report
What does BSI TR-03183-2 require of a software bill of materials, and how does it relate to the CRA?
BSI TR-03183-2 defines SBOM format, fields and depth; the SBOM inventories components and never carries vulnerability information.
Software bill of materials (SBOM) · Cyber Resilience Act (CRA) · Supply chain security · License management · Security advisory · Common Vulnerabilities and Exposures (CVE) · Vulnerability management
Read the cardContext card
Receiving vulnerability reports under BSI TR-03183-3: report, notification, advisory
What does BSI TR-03183-3 expect a manufacturer to have in place before the first vulnerability report arrives?
BSI TR-03183-3 sets up the intake for vulnerability reports: security.txt, PSIRT and CSIRT, CVD policy, response times and disclosure.
Coordinated vulnerability disclosure (CVD) · Vulnerability disclosure · Security advisory · Common Vulnerability Scoring System (CVSS) · Vulnerability management · Cyber Resilience Act (CRA)
Read the cardContext card
Module H under the CRA: BSI TR-03183-H builds full quality assurance on ISO/IEC 27001
How can a manufacturer demonstrate CRA conformity through its processes rather than product by product, and what does BSI TR-03183-H add?
BSI TR-03183-H shows how a CRA Module H quality system can rest on ISO/IEC 27001, audited by a notified body and still product-specific.
Conformity assessment · Notified body (MDR and IVDR) · Information security management system (ISMS) · Quality management · Security development lifecycle (SDL) · Harmonized standard · Presumption of conformity · Cyber Resilience Act (CRA)
Read the cardContext card
BSI guidance on the CRA: context-dependent, not contradictory
When two pieces of BSI guidance on the Cyber Resilience Act seem irreconcilable, is the guidance contradictory?
BSI TR-03183-1 ties every control to a risk scenario; apparent conflicts are resolved by the risk assessment, not irreconcilable advice.
Cyber Resilience Act (CRA) · Security risk assessment · Harmonized standard · Presumption of conformity · Software bill of materials (SBOM) · State of the art
Read the cardContext card
The explosion protection document after a conversion
When does the explosion protection document have to be updated?
The explosion protection document must follow every significant change of the plant; an extension or a moved booth is such a change (§ 6 GefStoffV).
Explosion protection document · Hazardous area classification (Ex zones) · Ordinance on Hazardous Substances (GefStoffV) · Grandfathering (work equipment) · Management of change (MOC) · Explosion protection · Retrofit
Read the cardContext card
BetrSichV or GefStoffV: which ordinance carries the duty?
Does the duty to keep the explosion protection document current come from the BetrSichV or the GefStoffV?
The explosion protection document rests on § 6 GefStoffV, not on the BetrSichV; same result, different legal basis — a frequent mix-up.
Ordinance on Industrial Safety and Health (BetrSichV) · Ordinance on Hazardous Substances (GefStoffV) · Explosion protection document · Presumption effect (technical rules) · Adaptation to the state of the art (work equipment) · Grandfathering (work equipment)
Read the cardContext card
Grandfathering covers the design, never the file
Does grandfathering protect an existing plant and its documentation?
No general grandfathering for work equipment in Germany: older designs may stay if safe, outdated risk assessments and documents never do.
Grandfathering (work equipment) · Ordinance on Industrial Safety and Health (BetrSichV) · Adaptation to the state of the art (work equipment) · Presumption effect (technical rules) · As-built documentation · Explosion protection document · State of the art
Read the cardContext card
Retrofit and substantial modification under the Machinery Regulation
When does a retrofit make the operator the manufacturer of a machine?
A retrofit turns the modifier into a manufacturer only if it is a substantial modification; every retrofit needs the risk assessment that decides it.
Retrofit · Retrofit under the Machinery Regulation · Substantial modification · Machinery Regulation (EU) 2023/1230 · Machinery Directive 2006/42/EC · Assembly of machinery · Stop controls of an assembly of machinery (1.2.4.4) · Ordinance on Industrial Safety and Health (BetrSichV) · Technical file · Safety PLC · Remote software update · Configuration management
Read the cardContext card
Topic-based vs. task-based documentation
Is topic-based documentation the same as task-based documentation?
Topic-based documentation defines the unit of content; task-based documentation defines which content is needed. The two are distinct and often combined.
DITA topic · DITA task · DITA concept · DITA reference · DITA map · DITA information typing
Read the cardContext card
Minimalism and structured authoring
How do minimalism and structured authoring work together?
Minimalism defines what content does for the user; structured authoring defines its form. Content models can turn minimalist principles into rules.
Schema (data) · Schema validation · DITA (Darwin Information Typing Architecture) · DITA task · DITA specialization · Information for use
Read the cardContext card
Every Page is Page One vs. semantic documentation
Is Every Page is Page One a form of semantic documentation?
EPPO is a writing model for self-contained pages; semantic documentation makes meaning machine-readable. Distinct models that strengthen each other.
DITA topic · Metadata · Taxonomy · Ontology · Information model · iiRDS Topic · Knowledge graph
Read the cardContext card
Six technical documentation models compared
How do topic-based, task-based, EPPO, semantic, minimalist and structured documentation differ?
Six documentation models answer six questions — unit, selection, independence, meaning, action and form — and are usually combined, not chosen.
Technical documentation · DITA (Darwin Information Typing Architecture) · DITA topic · DITA task · Metadata · Information model · Schema (data)
Read the cardContext card
Four types of SDK compared
What distinguishes developer, publishing, platform and hardware SDKs?
Developer, publishing, platform and hardware SDKs share one idea — a kit for building on something — but differ in target, artifacts, users and control.
Software development kit (SDK) · Application programming interface (API) · DITA (Darwin Information Typing Architecture) · Device driver · Firmware · Software library · Compiler
Read the cardContext card
How the four SDK types interoperate
Where do developer, publishing, platform and hardware SDKs meet in practice?
Hardware, developer, platform and publishing SDKs meet at gateways, APIs, extensions and documentation pipelines — held together by contracts and formats.
Interoperability · Interface contract · Serialization format · JSON · Distributed tracing · Observability · IoT gateway · Digital twin · Software bill of materials (SBOM)
Read the cardContext card
Extension points of a platform
How does a platform SDK let outside code extend a host application?
A platform SDK opens a host application at named extension points; a manifest declares contributions and permissions, and the host keeps control.
Software framework · Application programming interface (API) · Authorization · Interface contract · Backward compatibility · Deprecation path · Low-code/no-code platform
Read the cardContext card
Stages of a publishing pipeline
What happens to structured content inside a publishing SDK?
A publishing SDK resolves, validates, filters, transforms and packages structured content, so one source yields HTML, PDF and other deliverables.
DITA (Darwin Information Typing Architecture) · DITA map · DITA topic · DITA conditional processing · DITA content reference (conref) · DITA key · Schema validation · Metadata
Read the cardContext card
SDK vs. API
What is the difference between an SDK and an API?
An API is the contract between two pieces of software; an SDK is the kit of libraries, tools and samples that makes using that contract easier.
Software development kit (SDK) · Application programming interface (API) · REST API · Software library · Authentication · Interface contract · Semantic versioning
Read the cardContext card
Layers of a hardware SDK
Which layers does a hardware SDK provide between application code and a device?
A hardware SDK stacks toolchain, drivers, abstraction layer, runtime and libraries between application code and a device, plus tools to debug it.
Device driver · Firmware · Microcontroller (MCU) · Real-time operating system (RTOS) · Compiler · Debugging · Abstraction · Application binary interface (ABI) · Embedded software
Read the cardContext card
Control points for AI agents
Who controls what an AI agent is allowed to do?
An AI agent acts through identities, permissions, gateways and logs. The control points that bound it and what documentation has to record about them.
AI agent · Model Context Protocol (MCP) · Role-based access control (RBAC) · Principle of least privilege · Audit trail · Human in the loop · Logging
Read the cardContext card
AI vs. classical automation
How does AI differ from classical automation?
Classical automation executes predefined rules; AI derives its behavior from data. Why the two are combined and how AI output is bounded in operations.
Artificial intelligence (AI) · Automation · Machine learning (ML) · Programmable logic controller (PLC) · Robotic process automation (RPA) · Human in the loop
Read the cardContext card
MQTT vs. OPC UA: transport and meaning
What is the difference between MQTT and OPC UA?
MQTT moves messages through a broker; OPC UA adds an information model, services and security. How the two differ and why they are combined.
MQTT · OPC Unified Architecture (OPC UA) · Publish-subscribe pattern · Message broker · Information model · OPC UA PubSub
Read the card