diff --git a/.gitignore b/.gitignore
index 67d07686a..877c775c5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,3 +17,7 @@ output
 .venv
 .asv
 venv
+
+# Ignore vim swp files
+*.swp
+
diff --git a/docs/index.rst b/docs/index.rst
index 3eabac147..956224c47 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,6 +24,7 @@ Contents:
     quick-start
     api
     migrating
+    troubleshooting
 
 
 If you still can't find what you're looking for, try in one of the following pages:
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
new file mode 100644
index 000000000..8670d97a1
--- /dev/null
+++ b/docs/troubleshooting.rst
@@ -0,0 +1,34 @@
+===============
+Troubleshooting
+===============
+
+This troubleshooting guide includes common issues users have faced and tips for dealing with them.
+
+If you don't find answers to your problems here, be sure to check out ``betterproto``'s `Slack`!
+
+Upgrading betterproto in a poetry environment
+=============================================
+
+It seems like in some situations, installing and then updating ``betterproto`` 
+in ``poetry`` environments doesn't work. 
+If, after updating ``betterproto``, you're not getting the new features you wanted, 
+it might be because of the current virtual environment ``poetry`` has created. 
+While there's probably a "surgical" fix, we've found that removing the venv and re-installing it works.
+
+To do that, run ``poetry env info`` to see the venv path:
+
+.. code-block:: shell
+   :emphasize-lines: 5
+
+   $ poetry env info 
+   Virtualenv
+   Python:         3.8.7
+   Implementation: CPython
+   Path:           /home/username/.cache/pypoetry/virtualenvs/project-name-random-py3.8  # <-- THIS PATH
+   Valid:          True
+
+Then just ``rm -rf`` that path to delete the venv, 
+and re-create the env using ``poetry shell`` and ``poetry install``.
+
+.. _Slack: https://join.slack.com/t/betterproto/shared_invite/zt-f0n0uolx-iN8gBNrkPxtKHTLpG3o1OQ
+