diff --git a/imgui-sys/README.md b/docs/upgrading_imgui.md
similarity index 95%
rename from imgui-sys/README.md
rename to docs/upgrading_imgui.md
index c4303c8..0c0cdb0 100644
--- a/imgui-sys/README.md
+++ b/docs/upgrading_imgui.md
@@ -75,6 +75,8 @@ Luckily running the generator is quite straight forward:
 4. Run the generator as per https://github.com/cimgui/cimgui#using-generator
 5. Run `cargo xtask bindgen` and follow the rest of the steps as usual
 
+Note actually committing this change may be more complicated as you will need to either replace the submodule with a copy of the source, or update the cimgui submodule to point at your fork of imgui
+
 ## Common sources of problems
 
 ### Function changes
diff --git a/imgui-sys/README.markdown b/imgui-sys/README.markdown
new file mode 100644
index 0000000..1b7a8a2
--- /dev/null
+++ b/imgui-sys/README.markdown
@@ -0,0 +1,10 @@
+# imgui-sys: Low level bindings
+
+This crate contains the raw FFI bindings to the Dear ImGui C++
+library, by using the [cimgui](https://github.com/cimgui/cimgui) (a C
+API wrapper project for Dear ImGui), then creating Rust bindings using
+[bindgen](https://github.com/rust-lang/rust-bindgen).
+
+These low level, mostly `unsafe` bindings are then used by `imgui-rs`
+which wraps them in a nice to use, mostly safe API. Therefore most
+users should not need to interact with this crate directly.