From 7eb597857536604a1336e9c00c8d75bb852eab68 Mon Sep 17 00:00:00 2001 From: Martin Helmich Date: Mon, 2 Sep 2024 15:41:58 +0200 Subject: [PATCH] Reword extension overview for readability Precisely: - Do not assume (at least, in the introduction) that a reader is familiar with a glossary, and explain terms inline when used the first time - Reduce usage of passive expressions and nominalizations - Split up overly complex sentences --- docs/contribution/3-overview/1-extensions.mdx | 33 ++++++++++--------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/contribution/3-overview/1-extensions.mdx b/docs/contribution/3-overview/1-extensions.mdx index 20c72fa3..2fe26158 100644 --- a/docs/contribution/3-overview/1-extensions.mdx +++ b/docs/contribution/3-overview/1-extensions.mdx @@ -6,17 +6,17 @@ title: Extensions Aus fachlicher Sicht ist eine Extension eine Erweiterung des mStudio, die es ermöglicht, zusätzliche Funktionalitäten für das mStudio bereitzustellen. -Sie wird dem mStudio bekannt gemacht und kann von potenziellen Nutzern zu einem [Extension Context](../../glossary#extension-context) hinzugefügt werden. -Beim Hinzufügen einer Extension zu einem Extension Context wird eine [Extension Instance](../../glossary#extension-instance) erstellt. +Extensions werden dem mStudio [bekannt gemacht](../../how-to/create-extension), und potenzielle Nutzer können sie von dort aus in einem [Extension Context](../../glossary#extension-context) (beispielsweise also einem Projekt oder einer Organisation) installieren. +Wenn ein Nutzer eine Extension zu einem Extension Context hinzufügt, erstellt das mStudio eine [Extension Instance](../../glossary#extension-instance) für diese Extension. + Die Extension ist also die Beschreibung einer Erweiterung, die zu einem Extension Context hinzugefügt werden kann. Die Extension Instance ist die konkrete Ausprägung einer Extension in einem Extension Context. -Aus technischer Sicht ist eine Extension eine außerhalb des mStudio betriebene Applikation, -die über REST-APIs mit dem mStudio integriert wird. +Aus technischer Sicht ist eine Extension eine separate und unabhängige Applikation, die über REST-APIs mit dem mStudio kommuniziert. Eine Extension muss ein öffentlich erreichbares Backend bereitstellen und kann optional ein Frontend bereitstellen, wenn es für die Nutzung der Extension sinnvoll ist. -Das Backend einer Extension verarbeitet [Lifecycle Webhooks](../concepts/lifecycle-webhooks), -über die das mStudio die Extension über den Zustand ihrer Extension Instances informiert. +Wenn Extension Instances beispielsweise erstellt oder gelöscht werden, benachrichtigt das mStudio das Backend der Extension über einen [Lifecycle Webhook](../concepts/lifecycle-webhooks). + Außerdem bieten Extensions verschiedene [Authentifizierungs- und Authorisierungsstrategien](../concepts/authentication), um authentifizierte [Domain Actions](../../glossary#domain-action) im mStudio durchführen zu können. Dies kann entweder im Namen des mStudio Users, der die Extension bedient oder im Namen der Extension selbst geschehen. @@ -28,15 +28,16 @@ Im Folgenden soll ein grober Überblick gegeben werden. ### Name und Beschreibung -Eine Extension enthält 3 Stufen von Beschreibung. -Der Name und eine Kurzbeschreibung sind das erste, das ein Nutzer in der Übersicht von Extensions im Marktplatz sieht. -Daneben gibt es eine ausführliche Beschreibung, die mehr Details zur Extension enthält und Formattierung anbietet. +Eine Extension enthält drei verschiedene Beschreibungsfelder. + +Der **Name** und eine **Kurzbeschreibung** sind das erste, das ein Nutzer in der Extension-Übersicht im Marktplatz sieht. +Daneben gibt es eine **ausführliche Beschreibung**, die mehr Details zur Extension enthält und Formatierung anbietet. In dieser kann auf Features, Nutzungshinweise, weiterführende Links, einen Changelog und vieles mehr eingegangen werden. ### State -Um zu steuern, ob eine Extension im mStudio nutzbar sein soll, kann der State der Extension konfiguriert werden. -Über den State kann sowohl die Sichtbarkeit als auch die Installierbarkeit von Extensions gesteuert werden. +Der **State** der Extension definiert, ob sie im mStudio sicht- und nutzbar sein soll. +Das umfasst beispielsweise (jeweils unabhängig voneinander), ob sie generell aktiv ist, im Marktplatz angezeigt wird und ob sie zu einem Extension Context hinzugefügt werden kann. ### Tags @@ -55,9 +56,9 @@ Dazu muss mindestens eine E-Mail-Adresse angegeben werden, an die sich Nutzer we ### Scopes -Eine Extension muss Berechtigungen anfragen, um Domain Actions im mStudio durchführen zu können. -Dazu werden Scopes definiert, die die Berechtigungen der Extension beschreiben. -Für weitere Informationen zum Thema Scopes siehe [Scopes Konzept](../concepts/scopes). +Um über die REST-API des mStudios zugreifen, und dort **Domain Actions** durchführen zu können, benötigt eine Extension Berechtigungen, die vom Nutzer während der Installation bestätigt werden müssen. + +Diese Berechtigungen sind in Form von [**Scopes**](../concepts/scopes) definiert. Die Extension-Definition enthält eine Liste von Scopes, die die Berechtigungen der Extension beschreiben. ### Extension Context @@ -68,8 +69,8 @@ Die Entscheidung hängt von mehreren Faktoren, wie der Zielgruppe, dem Anwendung ### Lifecycle Webhook Endpoints Eine Extension muss definieren, an welche URLs Lifecycle-Webhooks gesendet werden sollen. -Über diese Webhooks wird der Extension mitgeteilt, welche Extension Instances existieren und in welchem Zustand sie sich befinden. -Für jeden Lifecycle kann ein eigener Webhook-Endpoint konfiguriert werden. +Über diese Webhooks teilt das mStudio der Extension mit, welche Extension Instances existieren und in welchem Zustand sie sich befinden. +Für jedes Lifecycle-Event kann ein eigener Webhook-Endpoint konfiguriert werden. Für weitere Informationen zu Lifecycle-Webhooks siehe [Lifecycle Webhooks Konzept](../concepts/lifecycle-webhooks). ### External Frontend