Best Practices: Workbench (#389)

* Notes on all topics to touch on * Scaffhold topics + intro & exploring UDFs fast * Adding Experimenting with UDF + Visualising results * adding Visualize & Naviguating workbench text * Added videos to S3 * Adding format your code * Typo fixes & small rewording --------- Co-authored-by: Maxime Lenormand <maximelenormand@maximes-mbp-2.home>
fusedio · Feb 7, 2025 · dae1492 · dae1492
1 parent e4a1297
commit dae1492
Show file tree

Hide file tree

Showing 7 changed files with 102 additions and 3 deletions.
diff --git a/docs/user-guide/best-practices/workbench-best-practices.mdx b/docs/user-guide/best-practices/workbench-best-practices.mdx
@@ -3,10 +3,109 @@ id: workbench-best-practices
 title: Workbench Best Practices
 sidebar_label: Workbench 
 sidebar_position: 1
-draft: true
 ---
 
-{/* TODO: Keeping this unlisted for now, only adding to check how this would look like */}
 # Workbench best practices
 
-🚧 Under construction 🚧
+_Tips & Tricks for making [Fused Workbench](/workbench/) work for you_
+
+import ReactPlayer from 'react-player';
+
+![Workbench Overview](/img/user-guide/best-practices/workbench_overview.png)
+
+[Workbench](/workbench/) is a web-IDE built to make working with Fused UDFs even faster! 
+
+## Experimenting with UDFs, fast
+
+In [UDF Builder](/workbench/udf-builder/) you have access to a [Code Editor](/workbench/udf-builder/code-editor/) that runs your UDFs and outputs results directly on the [Map View](/workbench/udf-builder/map/) for you. As soon as you make changes they show up in Map View! 
+
+### 💡 Leverage all the [UDF Best Practices](/user-guide/best-practices/udf-best-practices/)
+
+While this page is for Workbench, it builds on top of all the [Best Practices](/user-guide/best-practices/udf-best-practices/) that make your UDF fast & efficient. So if you haven't yet, take a look at our [dedicated UDF Best Practices](/user-guide/best-practices/udf-best-practices/).
+
+### Use `return` to quickly explore data
+
+Your UDF will stop at the first `return` it sees, which you can use to your advantage to return an intermediate result and explore it directly on the map:
+
+<details>
+    <summary>Example: Exploring `bbox` mid-UDF</summary>
+
+    In this example, we're using the [Overture Maps Example UDF](https://www.fused.io/workbench/catalog/Overture_Maps_Example-77970462-8c4d-44dd-87ad-3520f5d7bd83) but not sure exactly what our `bbox` object looks like.
+
+    The easiest way to check is simply to return it inside our UDF before any other logic:
+
+    <ReactPlayer className="video__player" playing={true} muted={true} controls height="100%" url="https://fused-magic.s3.us-west-2.amazonaws.com/workbench-walkthrough-videos/docs_rewrite/user-guide/best-practices/workbench_return_early_1080p_socials.mp4" width="100%" />
+
+</details>
+
+### Use Workbench to explore data on top of Python
+
+While you might be tempted to explore a specific row of a `GeoDataFrame` by filtering it and printing it, sometimes it faster to just click on it in [Map View](/workbench/udf-builder/map/) and explore in the [Selected Object section](/workbench/udf-builder/results/#selected-object)
+
+<ReactPlayer className="video__player" playing={false} muted={true} controls height="100%" url="https://fused-magic.s3.us-west-2.amazonaws.com/workbench-walkthrough-videos/docs_rewrite/user-guide/best-practices/workbench_eiffel_tower_exploring.mp4" width="100%" />
+
+### Format your code for more visibility
+
+You can hit `Opt + Shift + F` (or `Alt + Shift + F` on Windows/Linux) to format your code with a smaller line-length. This comes in handy if you don't want to scroll left and right to read your code, at the expense of having a bit more up and down scrolling to do
+
+
+## 🗺️ Visualizing results
+
+### Changing map view
+
+Map View supports [multiple base maps](/workbench/udf-builder/map/#map-controls) that might be better suited for different uses cases.
+
+- ⧉ Sometimes you just want a neutral basemap to focus on your data -> "Light" or "Dark" or even "Blank" basemaps are best
+- 🌍 Other times you might want some context, in which case using the "Satellite" basemap will suit your need best
+
+![Changing Map View](/img/user-guide/best-practices/workbench_map_view.png)
+
+### Using the Visualize Tab 
+
+You can easily change the styling of your data in the [Visualize Tab](/workbench/udf-builder/styling/):
+- [Changing the color of your data](/workbench/udf-builder/styling/#color-styling) (especially for vector files)
+- Using Visualize presets under "Surprised Me"
+- [Creating your own custom `loadingLayer`](/workbench/udf-builder/styling/#custom-loadinglayer-and-errorlayer)
+
+![Changing Map View](/img/user-guide/best-practices/workbench_visualise_surprise_me.png)
+
+### Tilt Map view to explore 3D datasets
+
+Map View gives you a top-level view of the world by default. But hold `Cmd` (or `Ctrl` on Windows / Mac) to tilt the view!
+
+![Tilted View](/img/user-guide/best-practices/workbench_tilted_view.png)
+
+🏘️ This can be really helpful to explore 3D datasets like in this [DSM Zonal Stats UDF](https://www.fused.io/workbench/catalog/DSM_Zonal_Stats-0c801e56-d0c4-47e8-a5ce-90d37703bdb7).
+
+## Navigating Workbench
+
+### Using Keyboard Shortcuts: Omnisearch
+
+Workbench has built-in keyboard shortcuts & quick navigation features: Hit `Cmd + K` (or `Ctrl + K` on Windows / Linux) to bring up Omnisearch:
+
+![Omnisearch](/img/user-guide/best-practices/workbench_omnisearch.png)
+
+Without lifting your hands from the keyboard you can:
+- Open a New UDF
+- Search the Docs, directly in Workbench!
+- See some of the most helpful Keyboard Shortcuts
+
+You'll find a more extended list of Keyboard Shortcuts under "Preferences":
+
+![Preferences - Keyboard Shortcuts](/img/user-guide/best-practices/workbench_keyboard_shortcuts.png)
+
+### Quickly jump from UDF Builder to File Explorer
+
+UDF Builder & File Explorer work well together, so we've made easy to jump from one to the other
+
+ {/* TODO: need video showing this once its in production*/}
+- In UDF Builder, `Cmd + Click` on a `s3://...` path will open it directly in File Explorer
+- In File Explorer double clicking on a file will prompt Fused to do its best at guessing which Catalog UDF to use to load this file in Code Editor
+
+## Troubleshooting
+
+If things feel a bit off, for example your UDF output looks suspicious here are a few things you can do:
+- Manually rerun the UDF with `Shift + Enter`
+- Check how much RAM your tab is using (in Chrome can easily do so by hovering the tab). Sometimes too much data is brought in to your browser and while we do our best to manage it properly it can get out of hand. A good old tab refresh goes a long way
+
+<ReactPlayer className="video__player" playing={false} muted={true} controls height="100%" url="https://fused-magic.s3.us-west-2.amazonaws.com/workbench-walkthrough-videos/docs_rewrite/user-guide/best-practices/workbench_refresh_tab.mp4" width="100%" />
diff --git a/static/img/user-guide/best-practices/workbench_keyboard_shortcuts.png b/static/img/user-guide/best-practices/workbench_keyboard_shortcuts.png
diff --git a/static/img/user-guide/best-practices/workbench_map_view.png b/static/img/user-guide/best-practices/workbench_map_view.png
diff --git a/static/img/user-guide/best-practices/workbench_omnisearch.png b/static/img/user-guide/best-practices/workbench_omnisearch.png
diff --git a/static/img/user-guide/best-practices/workbench_overview.png b/static/img/user-guide/best-practices/workbench_overview.png
diff --git a/static/img/user-guide/best-practices/workbench_tilted_view.png b/static/img/user-guide/best-practices/workbench_tilted_view.png
diff --git a/static/img/user-guide/best-practices/workbench_visualise_surprise_me.png b/static/img/user-guide/best-practices/workbench_visualise_surprise_me.png