diff --git a/client/client.go b/client/client.go
index 224ed6f454..8d32976b2b 100644
--- a/client/client.go
+++ b/client/client.go
@@ -6,9 +6,10 @@ https://docs.docker.com/engine/api/
 
 # Usage
 
-You use the library by creating a client object and calling methods on it. The
-client can be created either from environment variables with NewClientWithOpts(client.FromEnv),
-or configured manually with NewClient().
+You use the library by constructing a client object using [NewClientWithOpts]
+and calling methods on it. The client can be configured from environment
+variables by passing the [FromEnv] option, or configured manually by passing any
+of the other available [Opts].
 
 For example, to list running containers (the equivalent of "docker ps"):
 
diff --git a/client/client_deprecated.go b/client/client_deprecated.go
index 54cdfc29a8..9e366ce20d 100644
--- a/client/client_deprecated.go
+++ b/client/client_deprecated.go
@@ -9,7 +9,11 @@ import "net/http"
 // It won't send any version information if the version number is empty. It is
 // highly recommended that you set a version or your client may break if the
 // server is upgraded.
-// Deprecated: use NewClientWithOpts
+//
+// Deprecated: use [NewClientWithOpts] passing the [WithHost], [WithVersion],
+// [WithHTTPClient] and [WithHTTPHeaders] options. We recommend enabling API
+// version negotiation by passing the [WithAPIVersionNegotiation] option instead
+// of WithVersion.
 func NewClient(host string, version string, client *http.Client, httpHeaders map[string]string) (*Client, error) {
 	return NewClientWithOpts(WithHost(host), WithVersion(version), WithHTTPClient(client), WithHTTPHeaders(httpHeaders))
 }
@@ -17,7 +21,7 @@ func NewClient(host string, version string, client *http.Client, httpHeaders map
 // NewEnvClient initializes a new API client based on environment variables.
 // See FromEnv for a list of support environment variables.
 //
-// Deprecated: use NewClientWithOpts(FromEnv)
+// Deprecated: use [NewClientWithOpts] passing the [FromEnv] option.
 func NewEnvClient() (*Client, error) {
 	return NewClientWithOpts(FromEnv)
 }