From f5c4dc2d73b979048a4c15f7e7dfca958bc1339b Mon Sep 17 00:00:00 2001
From: Max Marrone <max@opentrons.com>
Date: Wed, 13 Dec 2023 18:11:19 -0500
Subject: [PATCH] docs(shared-data): Tidy up addressable area and fixture field
 descriptions (#14190)

---
 shared-data/deck/schemas/4.json | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/shared-data/deck/schemas/4.json b/shared-data/deck/schemas/4.json
index 719ce41f0c8..099a8f45a32 100644
--- a/shared-data/deck/schemas/4.json
+++ b/shared-data/deck/schemas/4.json
@@ -41,7 +41,6 @@
     },
     "boundingBox": {
       "type": "object",
-      "description": "The active area (both pipettes can reach) of a fixture on the deck",
       "required": ["xDimension", "yDimension", "zDimension"],
       "properties": {
         "xDimension": { "$ref": "#/definitions/positiveNumber" },
@@ -119,9 +118,9 @@
       "properties": {
         "addressableAreas": {
           "type": "array",
-          "description": "Ordered slots available for placing labware",
           "items": {
             "type": "object",
+            "description": "An addressable area is a named area in 3D space that the robot can interact with--for example, as a place to drop tips, or hold a labware.",
             "required": [
               "id",
               "areaType",
@@ -135,7 +134,7 @@
                 "type": "string"
               },
               "areaType": {
-                "description": "The type of deck item, defining allowed behavior.",
+                "description": "The type of addressable area, defining allowed behavior.",
                 "type": "string",
                 "enum": [
                   "slot",
@@ -147,13 +146,14 @@
               },
               "offsetFromCutoutFixture": {
                 "$ref": "#/definitions/xyzArray",
-                "description": "Relative offset of the addressable area as it sits on the cutout slot."
+                "description": "The offset from the origin of the cutout fixture that's providing this addressable area (which is currently identical to the position of the underlying cutout), to the -x, -y, -z corner of this addressable area's bounding box."
               },
               "matingSurfaceUnitVector": {
                 "$ref": "#/definitions/unitVector",
-                "description": "An optional diagonal direction of force, defined by spring location, which governs the mating surface of objects placed in slot."
+                "description": "An optional diagonal direction of force, defined by spring location, which governs the mating surface of objects placed in this addressable area. Meant to be used when this addressable area is a slot."
               },
               "boundingBox": {
+                "description": "The active area (both pipettes can reach) of this addressable area.",
                 "$ref": "#/definitions/boundingBox"
               },
               "displayName": {
@@ -252,6 +252,7 @@
     "cutoutFixtures": {
       "type": "array",
       "items": {
+        "description": "A cutout fixture is a physical thing that can be mounted onto one of the deck cutouts.",
         "type": "object",
         "required": [
           "id",
@@ -277,7 +278,7 @@
             "type": "string"
           },
           "providesAddressableAreas": {
-            "description": "A mapping of mayMountTo locations to addressableArea ids.",
+            "description": "The addressable areas that this cutout fixture provides, when it's mounted. It can provide different addressable areas depending on where it's mounted. Keys must match values from this object's `mayMountTo`. Values must match `id`s from `addressableAreas`.",
             "type": "object",
             "additionalProperties": {
               "type": "array",