diff --git a/ci/release/template/man/d2.1 b/ci/release/template/man/d2.1
index 8cf1ce5e2..d46ca20bf 100644
--- a/ci/release/template/man/d2.1
+++ b/ci/release/template/man/d2.1
@@ -9,14 +9,7 @@
 .Op Fl -watch Ar false
 .Op Fl -theme Em 0
 .Ar file.d2
-.Op Ar file.svg
-|
-.Op Ar file.png
-.Nm d2
-.Op Fl -watch Ar false
-.Op Fl -theme Em 0
-.Ar file.d2
-.Op Ar ...
+.Op Ar file.svg | file.png
 .Nm d2
 .Ar layout Op Ar name
 .Sh DESCRIPTION
@@ -29,10 +22,21 @@ to
 .Ar file.png
 .Ns .
 .Pp
+It defaults to
+.Ar file.svg
+if no output path is passed.
+.Pp
 Pass - to have
 .Nm
 read from stdin or write to stdout.
 .Pp
+Never use the presence of the output file to check for success.
+Always use the exit status of
+.Nm d2
+.Ns .
+This is because sometimes when errors occur while rendering, d2 still write out a partial
+render anyway to enable iteration on a broken diagram.
+.Pp
 See more docs, the source code and license at
 .Lk https://oss.terrastruct.com/d2
 .Sh OPTIONS
diff --git a/cmd/d2/help.go b/cmd/d2/help.go
index 98390495d..947c601e8 100644
--- a/cmd/d2/help.go
+++ b/cmd/d2/help.go
@@ -15,11 +15,15 @@ import (
 
 func help(ms *xmain.State) {
 	fmt.Fprintf(ms.Stdout, `Usage:
-  %s [--watch=false] [--theme=0] file.d2 [file.svg|file.png]
+  %s [--watch=false] [--theme=0] file.d2 [file.svg | file.png]
+
+%[1]s compiles and renders file.d2 to file.svg | file.png
+It defaults to file.svg if an output path is not provided.
 
-%[1]s compiles and renders file.d2 to file.svg|file.png.
 Use - to have d2 read from stdin or write to stdout.
 
+See man %[1]s for more detailed docs.
+
 Flags:
 %s