diff --git a/docs/latest/services/index.md b/docs/latest/services/index.md
index 15064f3a7..c8b35f6b2 100644
--- a/docs/latest/services/index.md
+++ b/docs/latest/services/index.md
@@ -1,9 +1,10 @@
-# Services
+# Services Overview
-- [Overview](#/)
-- [Anatomy](#/)
-- [UI Services](#/)
-- [Parting Words](#/)
+- [Overview](#overview)
+- [Kinds of Services](#kinds-of-services)
+ - [Services (default)](#services--default-)
+ - [UI Services](#ui-services)
+- [Related Patterns](#related-patterns)
## Overview
@@ -12,76 +13,24 @@ operations, often tied to some shared state, and are made available to
extensions via the `ServicesManager`. Services are particularly well suited to
address [cross-cutting concerns][cross-cutting-concerns].
-
-
-
-
-
Diagram showing relationship between React Context and UI Service
-
-
Each service should be:
- self-contained
- able to fail and/or be removed without breaking the application
- completely interchangeable with another module implementing the same interface
-### An Example
+## Kinds of Services
-The simplest service return a new object that has a `name` property, and
-methods/properties that give the service its functionality. The "Factory
-Function" that creates the service is provided with the implementation (this is
-slightly different for UI Services).
+Depending on the kind of service, we follow slightly different conventions. For
+example, a UI service often receives its implementation from a React Context
+Provider. You can read more about the different kinds of services and what makes
+them different below:
-```js
-const _speak = () => {
- console.warn('Speak is not implemented');
-};
+### Services (default)
-/**
- * Factory function to create `HelloWorldService`
- *
- * @param {object} implementation
- * @param {function} implementation.speak - Speak's implementation
- * @returns HelloWorldService
- */
-export default function createHelloWorldService({ speak }) {
- return {
- name: 'HelloWorldService',
- speak: speak || _speak,
- };
-}
-```
+...
-A service, once created, can be registered with the `ServicesManager` to make it
-accessible to extensions. Similarly, the application code can access named
-services from the `ServicesManager`.
-
-```js
-// In the application
-const speak = () => {
- window.alert('HELLO WORLD');
-};
-const HelloWorldService = createHelloWorldService({ speak });
-const servicesManager = new ServicesManager();
-
-servicesManager.registerService(HelloWorldService);
-
-// In an extension
-const { HelloWorldService } = servicesManager.services;
-
-if (HelloWorldService) {
- HelloWorldService.speak();
-}
-```
-
-### A work in progress
-
-Today, we only have maintained UI Services. You can read more about them below.
-
-In practice, services are live, but the patterns and guidance for them may shift
-slightly as we begin to develop real-world features that utilize them.
-
-## UI Services
+### UI Services
A typical web application will have components and state for common UI like
modals, notifications, dialogs, etc. A UI service makes it possible to leverage
@@ -89,14 +38,14 @@ these components from an extension.
We maintain the following UI Services:
-- [UIDialogService](./ui/ui-dialog-service.md)
-- [UIModalService](./ui/ui-modal-service.md)
-- [UINotificationService](./ui/ui-notification-service.md)
+- [UIDialogService](./ui-dialog-service.md)
+- [UIModalService](./ui-modal-service.md)
+- [UINotificationService](./ui-notification-service.md)
You can read more about a specific service by selecting it in the above list,
-and more about [UI services in general: here](./ui/index.md)
+and more about [UI services in general: here](./ui.md)
-## Parting Words
+## Related Patterns
Services are "concern-specific" code modules that can be consumed across layers.
We try to minimize the coupling they introduce by authoring services that are
diff --git a/docs/latest/services/service.md b/docs/latest/services/service.md
new file mode 100644
index 000000000..f6dae7d71
--- /dev/null
+++ b/docs/latest/services/service.md
@@ -0,0 +1,57 @@
+# Services
+
+
+
+
+
+
Diagram showing relationship between React Context and UI Service
+
+
+## Example
+
+The simplest service return a new object that has a `name` property, and
+methods/properties that give the service its functionality. The "Factory
+Function" that creates the service is provided with the implementation (this is
+slightly different for UI Services).
+
+```js
+const _speak = () => {
+ console.warn('Speak is not implemented');
+};
+
+/**
+ * Factory function to create `HelloWorldService`
+ *
+ * @param {object} implementation
+ * @param {function} implementation.speak - Speak's implementation
+ * @returns HelloWorldService
+ */
+export default function createHelloWorldService({ speak }) {
+ return {
+ name: 'HelloWorldService',
+ speak: speak || _speak,
+ };
+}
+```
+
+A service, once created, can be registered with the `ServicesManager` to make it
+accessible to extensions. Similarly, the application code can access named
+services from the `ServicesManager`.
+
+```js
+// In the application
+const speak = () => {
+ window.alert('HELLO WORLD');
+};
+const HelloWorldService = createHelloWorldService({ speak });
+const servicesManager = new ServicesManager();
+
+servicesManager.registerService(HelloWorldService);
+
+// In an extension
+const { HelloWorldService } = servicesManager.services;
+
+if (HelloWorldService) {
+ HelloWorldService.speak();
+}
+```
diff --git a/docs/latest/services/ui/ui-dialog-service.md b/docs/latest/services/ui-dialog-service.md
similarity index 100%
rename from docs/latest/services/ui/ui-dialog-service.md
rename to docs/latest/services/ui-dialog-service.md
diff --git a/docs/latest/services/ui/ui-modal-service.md b/docs/latest/services/ui-modal-service.md
similarity index 100%
rename from docs/latest/services/ui/ui-modal-service.md
rename to docs/latest/services/ui-modal-service.md
diff --git a/docs/latest/services/ui/ui-notification-service.md b/docs/latest/services/ui-notification-service.md
similarity index 100%
rename from docs/latest/services/ui/ui-notification-service.md
rename to docs/latest/services/ui-notification-service.md
diff --git a/docs/latest/services/ui/index.md b/docs/latest/services/ui.md
similarity index 100%
rename from docs/latest/services/ui/index.md
rename to docs/latest/services/ui.md