Add troubleshooting doc

docs/troubleshooting.md

@@ -0,0 +1,37 @@
+# Troubleshooting
+
+## Map does not display
+
+### `anywidget` not available
+
+Open the browser console to check for any errors generated by the JavaScript code, either with:
+
+- <kbd>option</kbd>+<kbd>command</kbd>+<kbd>I</kbd> or similar on Linux/Windows
+- Right click on the page and choose "inspect". (Note that in JupyterLab you may need to <kbd>Shift</kbd> + right click to access the browser menu.) Then in the top of the browser toolbar that opened on the right side of the screen, select "Console". Any errors will be highlighted in red.
+
+If you see something like
+
+```
+Failed to load model class 'AnyModel' from module 'anywidget'
+Error: No version of module anywidget is registered
+```
+
+then anywidget's JavaScript code is not available.
+
+This can happen if you installed Lonboard _after_ having launched Jupyter. Reloading the **browser tab** (not the Jupyter kernel) will usually fix this. In general, make sure you install Lonboard before launching Jupyter.
+
+If you're using Lonboard in a cloud-hosted Jupyter environment such as JupyterHub, you need to ensure that `anywidget` is installed in the environment from which Jupyter is launched. This is often different from the user's environment. See also more discussion in [issue #397](https://github.com/developmentseed/lonboard/issues/397).
+
+### Incompatible deck.gl versions
+
+There can only be one version of the JavaScript deck.gl library loaded by a single webpage. This means using other Jupyter widgets that also depend on deck.gl, such as [`maplibre`](https://github.com/eodaGmbH/py-maplibregl), will cause Lonboard to crash. See [issue #640](https://github.com/developmentseed/lonboard/issues/640).
+
+## Map displays but no data is visible
+
+If you don't see your data on the map, the most likely answer is that the data is displaying but with a configuration that makes it hard to see.
+
+As of Lonboard 0.10, only `lonboard.viz` will infer default rendering parameters that try to look "good". All layer constructors use deck.gl's default parameters, which may or may not default to what you want.
+
+For example, in a `ScatterplotLayer`, the default for `radius_units` is `"meters"`. So if you pass only `get_radius=10`, you likely won't see any data on the map because 10 meters is too small to render when zoomed out.
+
+To ensure that your data is in fact rendering, look for an attribute name ending in `min_pixels`. For example, the `ScatterplotLayer` has [`radius_min_pixels`](../api/layers/scatterplot-layer/#lonboard.ScatterplotLayer.radius_min_pixels). If you set this to `10`, then it should be easy to verify that the data was correctly loaded. Then from there you can customize the full suite of visualization parameters.

mkdocs.yml

@@ -89,9 +89,8 @@ nav:
       - ecosystem/jupyter-widgets.md
       - ecosystem/panel.md
       - ecosystem/shiny.md
-
-  # - Caveats: caveats.md
   - Performance: performance.md
+  - troubleshooting.md
   - Changelog: CHANGELOG.md
   - Alternatives: alternatives.md
   - "How it works?":