diff --git a/docs/jitsi-dev.md b/docs/jitsi-dev.md
index 24ec776ff0..b56b2019b3 100644
--- a/docs/jitsi-dev.md
+++ b/docs/jitsi-dev.md
@@ -50,7 +50,9 @@ communication layer with the client (all widgets *should* be talking to the clie
 over `postMessage`, even if they aren't going to be using the widget APIs).
 
 Widgets added with the `/addwidget` command will *not* be wrapped as they are not going
-through an integration manager.
+through an integration manager. The widgets themselves *should* also work outside of
+Riot. Widgets currently have a "pop out" button which opens them in a new tab and
+therefore have no connection back to Riot.
 
 ## Jitsi widgets from integration managers
 
@@ -67,7 +69,9 @@ will generate one for the user.
 
 When the user clicks on the call buttons by the composer, the integration manager is
 not involved in the slightest. Instead, Riot itself generates a widget event, this time
-using the config.json parameters, and publishes that to the room. 
+using the config.json parameters, and publishes that to the room. If there's only two
+people in the room, a plain WebRTC call is made instead of using a widget at all - these
+are defined in the Matrix specification.
 
 The Jitsi widget created by Riot uses a local `jitsi.html` wrapper (or one hosted by
 `https://riot.im/app` for desktop users or those on non-https domains) as the widget
diff --git a/docs/jitsi.md b/docs/jitsi.md
index 43708ee373..d3631ee8db 100644
--- a/docs/jitsi.md
+++ b/docs/jitsi.md
@@ -4,15 +4,15 @@ Riot uses [Jitsi](https://jitsi.org/) for conference calls, which provides optio
 self-hosting your own server and supports most major platforms.
 
 1:1 calls, or calls between you and one other person, do not use Jitsi. Instead, those
-calls work through a TURN server configured on your respective homeservers.
+calls work directly between clients or via TURN servers configured on the respective 
+homeservers.
 
 There's a number of ways to start a Jitsi call: the easiest way is to click on the 
 voice or video buttons near the message composer in a room with more than 2 people. This
 will add a Jitsi widget which allows anyone in the room to join.
 
 Integration managers (available through the 4 squares in the top right of the room) may
-provide their own approaches for adding Jitsi widgets, though these are now considered
-legacy and should only be used in specific circumstances.
+provide their own approaches for adding Jitsi widgets.
 
 ## Configuring Riot to use your self-hosted Jitsi server
 
@@ -44,4 +44,4 @@ domain will appear later in the URL as a configuration parameter.
 Currently the Riot mobile apps do not support custom Jitsi servers and will instead
 use the default `jitsi.riot.im` server. When users on the mobile apps join the call,
 they will be joining a different conference which has the same name, but not the same
-participants.
+participants. This is a known bug and which needs to be fixed.