diff --git a/spec/compiler/crystal/tools/doc_spec.cr b/spec/compiler/crystal/tools/doc_spec.cr
index 38edd287961f..96ea75f772d6 100644
--- a/spec/compiler/crystal/tools/doc_spec.cr
+++ b/spec/compiler/crystal/tools/doc_spec.cr
@@ -97,4 +97,28 @@ describe Crystal::Doc::ProjectInfo do
       end
     end
   end
+
+  it "find_default_name" do
+    with_tempfile("docs-shard-name") do |tempdir|
+      Dir.mkdir tempdir
+      Dir.cd(tempdir) do
+        Crystal::Doc::ProjectInfo.find_default_name.should be_nil
+
+        File.write("shard.yml", "foo: bar\n")
+        Crystal::Doc::ProjectInfo.find_default_name.should be_nil
+
+        File.write("shard.yml", "name: \n")
+        Crystal::Doc::ProjectInfo.find_default_name.should be_nil
+
+        File.write("shard.yml", "  name: bar\n")
+        Crystal::Doc::ProjectInfo.find_default_name.should be_nil
+
+        File.write("shard.yml", "name: bar\n")
+        Crystal::Doc::ProjectInfo.find_default_name.should eq "bar"
+
+        File.write("shard.yml", "name: bar # comment\n")
+        Crystal::Doc::ProjectInfo.find_default_name.should eq "bar"
+      end
+    end
+  end
 end
diff --git a/src/compiler/crystal/command/docs.cr b/src/compiler/crystal/command/docs.cr
index f19b7d489ab1..9292d8c63a18 100644
--- a/src/compiler/crystal/command/docs.cr
+++ b/src/compiler/crystal/command/docs.cr
@@ -98,12 +98,7 @@ class Crystal::Command
       setup_compiler_warning_options(opts, compiler)
     end
 
-    unless project_name
-      abort "missing --project-name"
-    end
-
-    project_version ||= Doc::ProjectInfo.find_default_project_version
-    project_info = Doc::ProjectInfo.new(project_name.not_nil!, project_version)
+    project_info = create_project_info(project_name, project_version)
 
     if options.empty?
       sources = [Compiler::Source.new("require", %(require "./src/**"))]
@@ -125,4 +120,22 @@ class Crystal::Command
     report_warnings result
     exit 1 if warnings_fail_on_exit?(result)
   end
+
+  private def create_project_info(name, version)
+    name ||= Doc::ProjectInfo.find_default_name
+    unless name
+      STDERR.puts "Couldn't determine name from shard.yml, please provide --project-name option"
+    end
+
+    version ||= Doc::ProjectInfo.find_default_version
+    unless version
+      STDERR.puts "Couldn't determine version from git, please provide --project-version option"
+    end
+
+    unless name && version
+      abort
+    end
+
+    Doc::ProjectInfo.new(name, version)
+  end
 end