diff --git a/docs/model/protocol_examples.rst b/docs/model/protocol_examples.rst
new file mode 100644
index 0000000000..61a599b432
--- /dev/null
+++ b/docs/model/protocol_examples.rst
@@ -0,0 +1,64 @@
+PUT /send/abc/ HTTP/1.1
+Host: ...
+Content-Length: ...
+Content-Type: application/json
+
+{
+ "origin": "localhost:5000",
+ "pdus": [
+ {
+ "content": {},
+ "context": "tng",
+ "depth": 12,
+ "is_state": false,
+ "origin": "localhost:5000",
+ "pdu_id": 1404381396854,
+ "pdu_type": "feedback",
+ "prev_pdus": [
+ [
+ "1404381395883",
+ "localhost:6000"
+ ]
+ ],
+ "ts": 1404381427581
+ }
+ ],
+ "prev_ids": [
+ "1404381396852"
+ ],
+ "ts": 1404381427823
+}
+
+HTTP/1.1 200 OK
+...
+
+======================================
+
+GET /pull/-1/ HTTP/1.1
+Host: ...
+Content-Length: 0
+
+HTTP/1.1 200 OK
+Content-Length: ...
+Content-Type: application/json
+
+{
+ origin: ...,
+ prev_ids: ...,
+ data: [
+ {
+ data_id: ...,
+ prev_pdus: [...],
+ depth: ...,
+ ts: ...,
+ context: ...,
+ origin: ...,
+ content: {
+ ...
+ }
+ },
+ ...,
+ ]
+}
+
+
diff --git a/docs/model/terminology.rst b/docs/model/terminology.rst
new file mode 100644
index 0000000000..cc6e6760ac
--- /dev/null
+++ b/docs/model/terminology.rst
@@ -0,0 +1,86 @@
+===========
+Terminology
+===========
+
+A list of definitions of specific terminology used among these documents.
+These terms were originally taken from the server-server documentation, and may
+not currently match the exact meanings used in other places; though as a
+medium-term goal we should encourage the unification of this terminology.
+
+
+Terms
+=====
+
+Backfilling:
+ The process of synchronising historic state from one home server to another,
+ to backfill the event storage so that scrollback can be presented to the
+ client(s). (Formerly, and confusingly, called 'pagination')
+
+Context:
+ A single human-level entity of interest (currently, a chat room)
+
+EDU (Ephemeral Data Unit):
+ A message that relates directly to a given pair of home servers that are
+ exchanging it. EDUs are short-lived messages that related only to one single
+ pair of servers; they are not persisted for a long time and are not forwarded
+ on to other servers. Because of this, they have no internal ID nor previous
+ EDUs reference chain.
+
+Event:
+ A record of activity that records a single thing that happened on to a context
+ (currently, a chat room). These are the "chat messages" that Synapse makes
+ available.
+ [[NOTE(paul): The current server-server implementation calls these simply
+ "messages" but the term is too ambiguous here; I've called them Events]]
+
+PDU (Persistent Data Unit):
+ A message that relates to a single context, irrespective of the server that
+ is communicating it. PDUs either encode a single Event, or a single State
+ change. A PDU is referred to by its PDU ID; the pair of its origin server
+ and local reference from that server.
+
+PDU ID:
+ The pair of PDU Origin and PDU Reference, that together globally uniquely
+ refers to a specific PDU.
+
+PDU Origin:
+ The name of the origin server that generated a given PDU. This may not be the
+ server from which it has been received, due to the way they are copied around
+ from server to server. The origin always records the original server that
+ created it.
+
+PDU Reference:
+ A local ID used to refer to a specific PDU from a given origin server. These
+ references are opaque at the protocol level, but may optionally have some
+ structured meaning within a given origin server or implementation.
+
+Presence:
+ The concept of whether a user is currently online, how available they declare
+ they are, and so on. See also: doc/model/presence
+
+Profile:
+ A set of metadata about a user, such as a display name, provided for the
+ benefit of other users. See also: doc/model/profiles
+
+Room ID:
+ An opaque string (of as-yet undecided format) that identifies a particular
+ room and used in PDUs referring to it.
+
+Room Alias:
+ A human-readable string of the form #name:some.domain that users can use as a
+ pointer to identify a room; a Directory Server will map this to its Room ID
+
+State:
+ A set of metadata maintained about a Context, which is replicated among the
+ servers in addition to the history of Events.
+
+User ID:
+ A string of the form @localpart:domain.name that identifies a user for
+ wire-protocol purposes. The localpart is meaningless outside of a particular
+ home server. This takes a human-readable form that end-users can use directly
+ if they so wish, avoiding the 3PIDs.
+
+Transaction:
+ A message which relates to the communication between a given pair of servers.
+ A transaction contains possibly-empty lists of PDUs and EDUs.
+
|
