diff --git a/ops/model.py b/ops/model.py
index 304af8fe9..2b4343d65 100644
--- a/ops/model.py
+++ b/ops/model.py
@@ -597,14 +597,11 @@ def open_port(self, protocol: typing.Literal['tcp', 'udp', 'icmp'],
                   port: Optional[int] = None):
         """Open a port with the given protocol for this unit.
 
-        Calling this registers intent with Juju that the application should be
-        accessed on the given port, but the port isn't actually opened
-        externally until the admin runs "juju expose".
-
-        On Kubernetes sidecar charms, the ports opened are not strictly
-        per-unit: Juju will open the union of ports from all units.
-        However, normally charms should make the same open_port() call from
-        every unit.
+        Some behaviour, such as whether the port is opened externally without
+        using "juju expose" and whether the opened ports are per-unit, differs
+        between Kubernetes and machine charms. See the
+        `Juju documentation <https://juju.is/docs/sdk/hook-tool#heading--open-port>`__
+        for more detail.
 
         Args:
             protocol: String representing the protocol; must be one of
@@ -619,10 +616,11 @@ def close_port(self, protocol: typing.Literal['tcp', 'udp', 'icmp'],
                    port: Optional[int] = None):
         """Close a port with the given protocol for this unit.
 
-        On Kubernetes sidecar charms, Juju will only close the port once the
-        last unit that opened that port has closed it. However, this is
-        usually not an issue; normally charms should make the same
-        close_port() call from every unit.
+        Some behaviour, such as whether the port is closed externally without
+        using "juju unexpose", differs between Kubernetes and machine charms.
+        See the
+        `Juju documentation <https://juju.is/docs/sdk/hook-tool#heading--close-port>`__
+        for more detail.
 
         Args:
             protocol: String representing the protocol; must be one of