diff --git a/docs/plugins/sort.rst b/docs/plugins/sort.rst
index 067e188fd..4ddef85cd 100644
--- a/docs/plugins/sort.rst
+++ b/docs/plugins/sort.rst
@@ -2,59 +2,37 @@ sort
 ====
 
 .. dfhack-tool::
-    :summary: Sort lists shown in the DF interface.
-    :tags: unavailable fort productivity interface
+    :summary: Search and sort lists shown in the DF interface.
+    :tags: fort productivity interface
     :no-command:
 
-.. dfhack-command:: sort-items
-   :summary: Sort the visible item list.
+The ``sort`` tool provides overlays that sorting and searching options for
+lists displayed in the DF interface.
 
-.. dfhack-command:: sort-units
-   :summary: Sort the visible unit list.
+Searching and sorting functionality is provided by `overlay` widgets, and widgets for individual lists can be moved via `gui/overlay` or turned on or off via `gui/control-panel`.
 
-Usage
------
+Squad assignment overlay
+------------------------
 
-::
+The squad assignment screen can be sorted by name, by migrant wave, or by various military-related skills.
 
-    sort-items <property> [<property> ...]
-    sort-units <property> [<property> ...]
+If sorted by "any melee", then the citizen is sorted according to the highest
+skill they have in axes, short swords, maces, warhammers, spears, or general
+fighting.
 
-Both commands sort the visible list using the given sequence of comparisons.
-Each property can be prefixed with a ``<`` or ``>`` character to indicate
-whether elements that don't have the given property defined go first or last
-(respectively) in the sorted list.
+If sorted by "any ranged", then the citizen is sorted according to the highest
+skill they have in crossbows or general ranged combat.
 
-Examples
---------
+If sorted by "leadership", then the citizen is sorted according to the highest
+skill they have in leader, teacher, or military tactics.
 
-``sort-items material type quality``
-    Sort a list of items by material, then by type, then by quality
-``sort-units profession name``
-    Sort a list of units by profession, then by name
+You can search for a dwarf by name by typing in the Search field. You can also
+type in the name of any job skill (military-related or not) and dwarves with
+any experience in that skill will be shown. For example, to only see citizens
+with military tactics skill, type in "tactics".
 
-Properties
-----------
+You can see all the job skill names that you can search for by running::
 
-Items can be sorted by the following properties:
+    :lua @df.job_skill
 
-- ``type``
-- ``description``
-- ``base_quality``
-- ``quality``
-- ``improvement``
-- ``wear``
-- ``material``
-
-Units can be sorted by the following properties:
-
-- ``name``
-- ``age``
-- ``arrival``
-- ``noble``
-- ``profession``
-- ``profession_class``
-- ``race``
-- ``squad``
-- ``squad_position``
-- ``happiness``
+in `gui/launcher`.