diff --git a/mlir/docs/Dialects/Linalg.md b/mlir/docs/Dialects/Linalg.md
--- a/mlir/docs/Dialects/Linalg.md
+++ b/mlir/docs/Dialects/Linalg.md
@@ -662,13 +662,16 @@
 }
 ```
 
-### YAML Based Named Structured Ops
+### YAML Based Named Structured Ops<a name="yaml-gen"></a>
 
 Linalg provides a declarative generation tool (`mlir-linalg-ods-yaml-gen`) to
 automatically produce named ops from a YAML-based op description format intended
-to capture the structure of the named ops and be generated from a higher level
-"mathy" DSL syntax. This facility is currently in flight and is intended to
-subsume the above when ready. See the C++ class to YAML mapping traits in
+to capture the structure of the named ops. The YAML-based op descriptions are
+generated from a higher level [DSL](../Tools/Linalg/OpDSL.md) and are not meant
+to be edited directly.
+
+This facility is currently in flight and is intended to subsume the above when
+ready. See the C++ class to YAML mapping traits in
 `mlir-mlinalg-ods-yaml-gen.cpp` as the source of truth for the schema.
 
 Most of the above documentation roughly applies to this path and will be ported
diff --git a/mlir/docs/Tools/LinalgOpDsl.md b/mlir/docs/Tools/Linalg/OpDSL.md
rename from mlir/docs/Tools/LinalgOpDsl.md
rename to mlir/docs/Tools/Linalg/OpDSL.md
--- a/mlir/docs/Tools/LinalgOpDsl.md
+++ b/mlir/docs/Tools/Linalg/OpDSL.md
@@ -1,12 +1,12 @@
-# linalg_opdsl tool
+# Linalg OpDSL
 
 Python based DSL for authoring Linalg op definitions and generating
 `linalg.generic` IR based on them for samples.
 
-The tool `linalg_opdsl` provides a high level DSL for constructing structured op
-definitions in a way that can be exported to built-in, named structured ops via
-the above YAML-based definitions or used interactively to emit corresponding
-`linalg.generic` IR for the composition.
+The Linalg OpDSL is a high level DSL for constructing structured op definitions
+in a way that can be exported to built-in, named structured ops via
+[YAML-based definitions](../../Dialects/Linalg.md/#yaml-gen) or used
+interactively to emit corresponding `linalg.generic` IR for the composition.
 
 ## Basic usage