README.md in rcee_isolated-0.1.0 vs README.md in rcee_isolated-0.2.0

@@ -1,2 +1,68 @@
+# RCEE::Isolated
 
 This gem is part of the Ruby C Extensions Explained project at https://github.com/flavorjones/ruby-c-extensions-explained
+
+## Summary
+
+This is the simplest viable C extension gem. It's named "Isolated" it's entirely self-contained, and doesn't call any external libraries.
+
+You might choose to write a C extension like this as a performance optimization if you have some CPU-intensive work to do. The BCrypt gem is a good example of this kind of C extension -- it's iterating over cryptographic math which is simply faster in C than it would be in Ruby.
+
+## Details
+
+This gem's C code is located in `ext/isolated/isolated.c` and includes this singleton method:
+
+``` C
+static VALUE
+rb_isolated_extension_class_do_something(VALUE self)
+{
+  /* todo: perform CPU-intensive operation */
+  return rb_str_new_cstr("something has been done");
+}
+
+void
+Init_isolated(void)
+{
+  rb_mRCEE = rb_define_module("RCEE");
+  rb_mIsolated = rb_define_module_under(rb_mRCEE, "Isolated");
+  rb_cIsolatedExtension = rb_define_class_under(rb_mIsolated, "Extension", rb_cObject);
+  rb_define_singleton_method(rb_cIsolatedExtension, "do_something",
+                             rb_isolated_extension_class_do_something, 0);
+}
+```
+
+The `extconf.rb` is as simple as it gets:
+
+``` ruby
+require "mkmf"
+
+create_makefile("rcee/isolated/isolated")
+```
+
+"mkmf" is short for MakeMakefile, a Ruby module that's shipped with the standard library. It defines "create_makefile" as well as a handful of other methods for advanced configuration, some of which we'll see in later examples.
+
+The "create_makefile" method is what actually writes the recipe for _compiling_ and _linking_. Because we haven't configured anything, it's going to adopt a set of reasonable defaults.
+
+The output `Makefile` is long and complex, but the recipe it implements is relatively simple and does something like:
+
+``` sh
+# `create_makefile` recipe is something like this
+
+# compile phase:
+gcc -c -I/path/to/ruby/include isolated.c -o isolated.o
+
+# link phase:
+gcc -shared -L/path/to/ruby/lib -lruby -lc -lm isolated.o -o isolated.so
+```
+
+That final shared library, `isolated.so`, is loaded like any other Ruby file, via `require` in `lib/rcee/isolated.rb`:
+
+``` ruby
+require_relative "isolated/isolated"
+```
+
+## What Can Go Wrong
+
+1. Users don't have the compiler toolchain installed (`gcc`, `ld`, `stdio.h`, `libc.so`, etc.)
+2. Users don't have the ruby development files installed (`ruby.h`, etc.)
+3. Users try to use the compiled extension on a different minor version of Ruby, a different CPU architecture, or a different operating system.