[Documentation] Update glossary, expand entry for dereferencing (#542)

* Update glossary, expand entry for dereferencing

* Add glossary as separate file

docs/federation/glossary.md

@@ -0,0 +1,73 @@
+# Glossary
+
+This document describes some commonly-used terms in discussions of federation.
+
+## `ActivityPub`
+
+A decentralized social networking protocol based on the ActivityStreams data format. See [here](https://www.w3.org/TR/activitypub/).
+
+GoToSocial uses the ActivityPub protocol to communicate between GtS servers, and with other federated servers like Mastodon, Pixelfed, etc.
+
+## `ActivityStreams`
+
+A model/data format for representing potential and completed activities using JSON. See [here](https://www.w3.org/TR/activitystreams-core/).
+
+GoToSocial uses the ActivityStreams data model to 'speak' ActivityPub with other servers.
+
+## `Actor`
+
+An actor is an ActivityStreams object that is capable of performing some Activity like following, liking, creating a post, reblogging, etc. See [here](https://www.w3.org/TR/activitypub/#actors).
+
+In GoToSocial, each account/user is an actor.
+
+## `Dereference`
+
+To 'dereference' a post or a profile means to make an HTTP call to the server that hosts that post or profile, in order to obtain its ActivityStreams representation.
+
+GoToSocial 'dereferences' posts and profiles on remote servers, in order to convert them to models that GoToSocial can understand and work with.
+
+Here's a more detailed explanation with some examples:
+
+Let's say that someone on an ActivityPub server searches for the username `@tobi@goblin.technology`.
+
+Their server would then do a webfinger lookup at `goblin.technology` for the username `tobi`, at the following URL:
+
+```text
+https://goblin.technology/.well-known/webfinger?resource=acct:tobi@goblin.technology
+```
+
+The `goblin.technology` server would give back some JSON in response; something like this:
+
+```json
+{
+  "subject": "acct:tobi@goblin.technology",
+  "aliases": [
+    "https://goblin.technology/users/tobi",
+    "https://goblin.technology/@tobi"
+  ],
+  "links": [
+    {
+      "rel": "http://webfinger.net/rel/profile-page",
+      "type": "text/html",
+      "href": "https://goblin.technology/@tobi"
+    },
+    {
+      "rel": "self",
+      "type": "application/activity+json",
+      "href": "https://goblin.technology/users/tobi"
+    }
+  ]
+}
+```
+
+Under the links section the requesting server would look for a link of type `application/activity+json`, which denotes the ActivityStreams representation of the user. In this case, the URL is:
+
+```text
+https://goblin.technology/users/tobi
+```
+
+The above URL is a *reference* to the activitypub representation of the user/Actor `tobi` on the `goblin.technology` instance. It's called a reference because it doesn't contain all of the information about that user, it's only a reference point for where that information can be found.
+
+Now, the requesting server will make a request to that URL in order to obtain a fuller representation of `@tobi@goblin.technology`, which complies to the ActivityPub spec. In other words, the server now follows a *reference* to get to the thing it references. This makes it *not a reference anymore*, hence the term *dereferencing*.
+
+For an analogy, consider what happens when you look something up in the index of a book: first you get the page number that the material you're interested in is on, which is a reference. Then you turn to the referenced page to see the content, which is dereferencing.

docs/federation/index.md

@@ -9,31 +9,3 @@ Not all of the servers you 'federate' with will be running GoToSocial: popular i
 This federated approach also means that you aren't beholden to arbitrary rules from some gigantic corporation potentially thousands of miles away. Your server has its own rules and culture; your fellow server residents are your neighbors; you will likely get to know your server admins and moderators, or be an admin yourself.
 
 GoToSocial advocates for many small, weird, specialist servers where people can feel at home, rather than a few big and generic ones where one person's voice can get lost in the crowd.
-
-## Glossary
-
-Some commonly-used terms in discussions of federation, and their meanings.
-
-### `ActivityPub`
-
-A decentralized social networking protocol based on the ActivityStreams data format. See [here](https://www.w3.org/TR/activitypub/).
-
-GoToSocial uses the ActivityPub protocol to communicate between GtS servers, and with other federated servers like Mastodon, Pixelfed, etc.
-
-### `ActivityStreams`
-
-A model/data format for representing potential and completed activities using JSON. See [here](https://www.w3.org/TR/activitystreams-core/).
-
-GoToSocial uses the ActivityStreams data model to 'speak' ActivityPub with other servers.
-
-### `Actor`
-
-An actor is an ActivityStreams object that is capable of performing some Activity like following, liking, creating a post, reblogging, etc. See [here](https://www.w3.org/TR/activitypub/#actors).
-
-In GoToSocial, each account/user is an actor.
-
-### `Dereference`
-
-To 'dereference' a post or a profile means to make an HTTP call to the server that hosts that post or profile, in order to obtain its ActivityStreams representation.
-
-GoToSocial 'dereferences' posts and profiles on remote servers, in order to convert them to models that GoToSocial can understand and work with.

mkdocs.yml

@@ -43,6 +43,7 @@ nav:
     - "user_guide/password_management.md"
   - "Federation":
     - "federation/index.md"
+    - "federation/glossary.md"
     - "federation/security.md"
     - "federation/behaviors/outbox.md"
     - "federation/behaviors/conversation_threads.md"