diff --git a/README.md b/README.md
index 6b0021d..9d334ed 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # bevy_mod_outline
 
-This crate provides a plugin for drawing outlines around meshes.
+This crate provides a Bevy plugin for drawing outlines around meshes using the
+vertex extrusion method.
 
 ## Dependency
 
@@ -22,3 +23,8 @@ cargo run --example cube
 | This Version | Bevy version |
 |--------------|--------------|
 | 0.1.x        | 0.7.x        |
+
+## Known Issues
+
+Vertex extrusion only works for meshes with smooth surface normals. Hard edges
+will cause visual artefacts.
\ No newline at end of file
diff --git a/src/lib.rs b/src/lib.rs
index 19b5326..8e902e4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -26,13 +26,18 @@ use bevy::render::view::ExtractedView;
 use bevy::render::{RenderApp, RenderStage};
 use libm::nextafterf;
 
+// See https://alexanderameye.github.io/notes/rendering-outlines/
+
 const OUTLINE_SHADER_HANDLE: HandleUntyped =
     HandleUntyped::weak_from_u64(Shader::TYPE_UUID, 2101625026478770097);
 
+/// An asset for rendering outlines around meshes.
 #[derive(Clone, TypeUuid)]
 #[uuid = "552e416b-2766-4e6a-9ee5-9ebd0e8c0230"]
 pub struct Outline {
+    /// Colour of the outline
     pub colour: Color,
+    /// Width of the outline in pixels
     pub width: f32,
 }
 
@@ -109,6 +114,7 @@ pub struct GpuOutline {
     transparent: bool,
 }
 
+/// Adds support for the [Outline] asset type.
 pub struct OutlinePlugin;
 
 impl Plugin for OutlinePlugin {