diff --git a/lib/puppet/resource_api.rb b/lib/puppet/resource_api.rb
index 0f9ba788..f36b3604 100644
--- a/lib/puppet/resource_api.rb
+++ b/lib/puppet/resource_api.rb
@@ -37,6 +37,16 @@ def register_type(definition)
     unknown_features = definition[:features] - supported_features
     Puppet.warning("Unknown feature detected: #{unknown_features.inspect}") unless unknown_features.empty?
 
+    # fixup desc/docs backwards compatibility
+    if definition.key? :docs
+      if definition[:desc]
+        raise Puppet::DevError, '`%{name}` has both `desc` and `docs`, prefer using `desc`' % { name: definition[:name] }
+      end
+      definition[:desc] = definition[:docs]
+      definition.delete(:docs)
+    end
+    Puppet.warning('`%{name}` has no documentation, add it using a `desc` key' % { name: definition[:name] }) unless definition.key? :desc
+
     # fixup any weird behavior  ;-)
     definition[:attributes].each do |name, attr|
       next unless attr[:behavior]
@@ -56,7 +66,7 @@ def register_type(definition)
     end
 
     Puppet::Type.newtype(definition[:name].to_sym) do
-      @docs = definition[:docs]
+      @docs = definition[:desc]
 
       # Keeps a copy of the provider around. Weird naming to avoid clashes with puppet's own `provider` member
       define_singleton_method(:my_provider) do
diff --git a/spec/puppet/resource_api/base_context_spec.rb b/spec/puppet/resource_api/base_context_spec.rb
index b7f4f724..3d42d10a 100644
--- a/spec/puppet/resource_api/base_context_spec.rb
+++ b/spec/puppet/resource_api/base_context_spec.rb
@@ -13,7 +13,7 @@ def send_log(log, msg)
     TestContext.new(definition)
   end
 
-  let(:definition) { { name: 'some_resource', attributes: { name: 'some_resource' }, features: feature_support } }
+  let(:definition) { { name: 'some_resource', desc: 'a test resource', attributes: { name: { type: 'String', desc: 'message' } }, features: feature_support } }
   let(:feature_support) { [] }
 
   it { expect { described_class.new(nil) }.to raise_error ArgumentError, %r{BaseContext requires definition to be a Hash} }
diff --git a/spec/puppet/resource_api/puppet_context_spec.rb b/spec/puppet/resource_api/puppet_context_spec.rb
index f64b0119..7b614733 100644
--- a/spec/puppet/resource_api/puppet_context_spec.rb
+++ b/spec/puppet/resource_api/puppet_context_spec.rb
@@ -3,7 +3,7 @@
 RSpec.describe Puppet::ResourceApi::PuppetContext do
   subject(:context) { described_class.new(definition) }
 
-  let(:definition) { { name: 'some_resource' } }
+  let(:definition) { { name: 'some_resource', desc: 'a test resource', attributes: {} } }
 
   describe '#device' do
     context 'when a NetworkDevice is configured' do
diff --git a/spec/puppet/resource_api_spec.rb b/spec/puppet/resource_api_spec.rb
index f383e72d..29446642 100644
--- a/spec/puppet/resource_api_spec.rb
+++ b/spec/puppet/resource_api_spec.rb
@@ -47,7 +47,10 @@
   context 'when registering a minimal type' do
     let(:definition) { { name: 'minimal', attributes: {} } }
 
-    it { expect { described_class.register_type(definition) }.not_to raise_error }
+    it {
+      expect(Puppet).to receive(:warning).with('`minimal` has no documentation, add it using a `desc` key')
+      described_class.register_type(definition)
+    }
 
     describe 'the registered type' do
       subject(:type) { Puppet::Type.type(:minimal) }
@@ -62,10 +65,33 @@
     end
   end
 
+  context 'when registering a type with both desc and docs key' do
+    let(:definition) { { name: 'both', desc: 'the desc', docs: 'the docs', attributes: {} } }
+
+    it {
+      expect { described_class.register_type(definition) }.to raise_error Puppet::DevError, '`both` has both `desc` and `docs`, prefer using `desc`'
+    }
+  end
+
+  context 'when registering a type with a docs key' do
+    let(:definition) { { name: 'both', docs: 'the docs', attributes: {} } }
+
+    it { expect { described_class.register_type(definition) }.not_to raise_error }
+
+    describe 'the registered type' do
+      subject(:type) { Puppet::Type.type(:both) }
+
+      it { is_expected.not_to be_nil }
+      it { is_expected.to be_respond_to :instances }
+      it { expect(type.instance_variable_get(:@docs)).to eq 'the docs' }
+    end
+  end
+
   context 'when registering a type with multiple attributes' do
     let(:definition) do
       {
         name: type_name,
+        desc: 'a test resource',
         attributes: {
           name: {
             type: 'String',
@@ -769,6 +795,7 @@ def set(_context, _changes); end
     let(:definition) do
       {
         name: 'init_behaviour',
+        desc: 'a test resource',
         attributes: {
           ensure: {
             type: 'Enum[present, absent]',
@@ -1253,7 +1280,7 @@ def set(_context, _changes); end
     context 'when loading a provider that doesn\'t create the correct class' do
       let(:definition) { { name: 'no_class', attributes: {} } }
 
-      it { expect { described_class.load_provider('no_class') }.to raise_error Puppet::DevError, %r{Puppet::Provider::NoClass::NoClass} }
+      it { expect { described_class.load_provider('no_class') }.to raise_error Puppet::DevError, %r{provider class Puppet::Provider::NoClass::NoClass not found} }
     end
 
     context 'when loading a provider that creates the correct class' do
@@ -1810,6 +1837,7 @@ def set(_context, changes) end
     let(:definition) do
       {
         name: 'test_noop_support',
+        desc: 'a test resource',
         features: ['no such feature'],
         attributes: {},
       }
@@ -1826,6 +1854,7 @@ def set(_context, changes) end
       let(:definition) do
         {
           name: 'test_behaviour',
+          desc: 'a test resource',
           attributes: {
             id: {
               type: 'String',
@@ -1842,6 +1871,7 @@ def set(_context, changes) end
       let(:definition) do
         {
           name: 'test_behaviour',
+          desc: 'a test resource',
           attributes: {
             param: {
               type: 'String',
@@ -1858,6 +1888,7 @@ def set(_context, changes) end
       let(:definition) do
         {
           name: 'test_behaviour',
+          desc: 'a test resource',
           attributes: {
             param_ro: {
               type: 'String',
@@ -1874,6 +1905,7 @@ def set(_context, changes) end
       let(:definition) do
         {
           name: 'test_behaviour',
+          desc: 'a test resource',
           attributes: {
             param_ro: {
               type: 'String',
@@ -1890,6 +1922,7 @@ def set(_context, changes) end
       let(:definition) do
         {
           name: 'test_behaviour',
+          desc: 'a test resource',
           attributes: {
             source: {
               type: 'String',