docs: ipns ttl tips (#2002)

Co-authored-by: Daniel Norman <[email protected]>

docs/concepts/ipns.md

@@ -18,6 +18,7 @@ description: Learn about mutability in IPFS, InterPlanetary Name System (IPNS),
         - [Publishing IPNS records over PubSub lifecycle](#publishing-ipns-records-over-pubsub-lifecycle)
     - [Tradeoffs between consistency vs. availability](#tradeoffs-between-consistency-vs-availability)
       - [IPNS record validity](#ipns-record-validity)
+      - [IPNS record TTL](#ipns-record-ttl)
       - [Practical considerations](#practical-considerations)
   - [IPNS in practice](#ipns-in-practice)
     - [Resolving IPNS names using IPFS gateways](#resolving-ipns-names-using-ipfs-gateways)
@@ -177,13 +178,32 @@ Availability means resolving to a valid IPNS record, at the cost of potentially
 
 When setting the `validity` (referred to as [`lifetime` by Kubo](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsrecordlifetime)) field of an IPNS record, you typically need to choose whether you favor **consistency** (short validity period, e.g. 48 hours) or **availability** (long validity period, e.g. 1 month), due to the inherent trade-off between the two.
 
+#### IPNS record TTL
+
+If you experience slow IPNS update propagation, the Time-to-Live (TTL) setting is the first thing to check.
+
+##### TTL as a Publisher
+
+When you publish an IPNS Record, the default TTL, which controls caching, might be set to a high value, such as one hour. If you want third-party gateways and nodes to bypass the cache and check for updates more frequently, consider lowering this value.
+
+- **Kubo**: Refer to the `--ttl` option in [`ipfs name publish --help`](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-name-publish) for details on adjusting this setting.
+- **Note**: If your IPNS Record is used behind a DNSLink (e.g., `/ipns/example.com` pointing to `/ipns/k51..libp2p-key`), the DNS TXT record at `_dnslink.example.com` has its own TTL. This DNS TTL also affects caching. Ensure that both TTL values are aligned for consistent behavior.
+
+##### TTL as a Gateway Operator
+
+You should have the ability to override the TTL provided by the publisher and set a lower cap on how long resolution results are cached.
+
+- **Kubo**: Configure this using the [`Ipns.MaxCacheTTL`](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsmaxcachettl) setting.
+- **Rainbow**: Adjust this with the [`RAINBOW_IPNS_MAX_CACHE_TTL`](https://github.com/ipfs/rainbow/blob/main/docs/environment-variables.md#rainbow_ipns_max_cache_ttl) environment variable.
+
 #### Practical considerations
 
-One of the most important things to consider with IPNS names is **how frequently you intend on updating the name**.
+The most important thing to consider with IPNS names is **how frequently you intend on updating the name** and **how long a valid record should be cached before checking for an update**.
 
-Practically, two levers within your control determine where your IPNS name is on the spectrum between consistency and availability:
+Practically, levers within your control determine where your IPNS name is on the spectrum between consistency and availability:
 
-- **IPNS record validity:** longer validity will veer towards availability. Moreover, longer validity will reduce the dependence on the key holder (which for most purposes is stored on a single machine and rare shared) since the record can continue to persist without requiring the private key holder to sign a new record. Another benefit of a longer validity is that the transport can be delegated to other nodes or services (such as [w3name](https://staging.web3.storage/docs/how-tos/w3name/)), without compromising the private key.
+- **IPNS record validity:** longer validity will veer towards availability. Moreover, longer validity will reduce the dependence on the key holder (which for most purposes is stored on a single machine and rare shared) since the record can continue to persist without requiring the private key holder to sign a new record. Another benefit of a longer validity is that the transport can be delegated to other nodes or services (such as [w3name](https://docs.storacha.network/how-to/w3name/)), without compromising the private key.
+- **IPNS record TTL:** longer TTL trades update propagation speed for better page load performance and resiliency.
 - **Transport mechanism:** the DHT veers towards consistency while PubSub veers towards availability. However, with Kubo, IPNS names are always published to the DHT, while PubSub is opt-in. For most purposes, enabling PubSub is a net gain unless you hit the upper limit of connections as a result of too many PubSub subscriptions.
 
 ## IPNS in practice