diff --git a/crates/typst-library/src/text/mod.rs b/crates/typst-library/src/text/mod.rs
index 6aeebbbaf..62c870513 100644
--- a/crates/typst-library/src/text/mod.rs
+++ b/crates/typst-library/src/text/mod.rs
@@ -495,7 +495,9 @@ pub struct TextElem {
     ///
     /// Hyphenation is generally avoided by placing the whole word on the next
     /// line, so a higher hyphenation cost can result in awkward justification
-    /// spacing.
+    /// spacing. Note: Hyphenation costs will only be applied when the
+    /// [`linebreaks`]($par.linebreaks) are set to "optimized". (For example
+    /// by default implied by [`justify`]($par.justify).)
     ///
     /// Runts are avoided by placing more or fewer words on previous lines, so a
     /// higher runt cost can result in more awkward in justification spacing.