README.md in leap_salesforce-0.1.12 vs README.md in leap_salesforce-0.1.13

@@ -53,10 +53,13 @@
 API Traffic logs can be seen in the `logs` folder. You can see an example of running through 
 this [here](https://asciinema.org/a/259098).
 
 ### Understanding how things work
  
+This section details what the most important files are, how to define test users
+ and how to create, read, update, and delete data. 
+ 
 #### Important files
 
 To see how things fit together, look at the [structure](#structure) section below.
 
 ##### `.leap_salesforce.yml` 
@@ -107,9 +110,60 @@
 # Using username that has a partial match with a Regex
 LeapSalesforce.api_user = LeapSalesforce::Users.where username: /admin/
 # Using description that has a partial match with a Regex. This might be helpful if you're setting users from 
 # a Cucumber step definition where readability is important 
 LeapSalesforce.api_user = LeapSalesforce::Users.where description: /System Admin/
+```
+
+#### CRUD of data
+
+To work data in Salesforce, an object inheriting from the `SoqlData` class is always used. The idea is
+that an object in Ruby code maps to the object in Salesforce and requests and updates to this object
+are reflected in Salesforce.
+
+When the initialisation script is run, it creates such classes in a folder called `soql_data`.
+
+Following a simple example of a class representing the 'ContentDocument' object in Salesforce. It 
+also requires a generated file that specifies accessors to set and retrieve information about the object.
+
+```ruby
+require_relative 'document_field_names'
+# An Document object mapping to a SOQL ContentDocument
+class Document < SoqlData
+  include Document::Fields
+  soql_object 'ContentDocument'
+end
+```
+
+For all interactions with Salesforce the API traffic logs are recorded in a log created in the `logs`
+folder of the suite.
+
+##### Creating entities
+
+There are several ways entities can be created. By instantiating the object with the `new` method a new
+object will be created in memory but in Salesforce. Only when the `save!` method is called will an object
+be created.
+
+For example
+
+```ruby
+@contact = Contact.new              # Create an object in memory
[e-mail]_name = 'Test Person'  # Set the last name field of that object to 'Test Person'
[e-mail]!                      # Calls Salesforce API to create a new object with the fields set in the object
+```
+
+The `log` for this call will look like the following:
+
+```verilog
+Leaps, [13:39:14] : Example Factory for 'Contact'
+Leaps, [13:39:14] : request body: {"FirstName":"Lewis","LastName":"Gleichner"}
+Leaps, [13:39:14] : RestClient.post "https://brave-otter-ttxype-dev-ed.my.salesforce.com/services/data/v45.0/sobjects/Contact", "{\"FirstName\":\"Lewis\",\"LastName\":\"Gleichner\"}", "Accept"=>"*/*", "Accept-Encoding"=>"gzip, deflate", "Authorization"=>"Bearer 00D2v000001eBDw!AREAQK_UWp9onsfZdv5ag5j70WIbwe_IG5tLJHKC1Ti0lpVZY0EsKcmpCE8bqTd7GtGx9WmN57PRpp06yhmfczK9TUR9rZx2", "Content-Length"=>"44", "Content-Type"=>"application/json", "User-Agent"=>"rest-client/2.0.2 (linux-gnu x86_64) ruby/2.6.0p0"
+
+Leaps, [13:39:16] : # => 201 Created | application/json 71 bytes
+
+Leaps, [13:39:16] : response: 
+  headers: {:date=>"Thu, 01 Aug 2019 01:39:15 GMT", :strict_transport_security=>"max-age=31536002; includeSubDomains", :public_key_pins_report_only=>"pin-sha256=\"9n0izTnSRF+W4W4JTq51avSXkWhQB8duS2bxVLfzXsY=\"; pin-sha256=\"5kJvNEMw0KjrCAu7eXY5HZdvyCS13BbA0VJG1RSP91w=\"; pin-sha256=\"njN4rRG+22dNXAi+yb8e3UMypgzPUPHlv4+foULwl1g=\"; max-age=86400; includeSubDomains; report-uri=\"https://a.forcesslreports.com/hpkp-report/00D2v000001eBDwm\";", :expect_ct=>"max-age=86400; report-uri=\"https://a.forcesslreports.com/Expect-CT-report/00D2v000001eBDwm\";", :x_content_type_options=>"nosniff", :x_xss_protection=>"1; mode=block", :x_robots_tag=>"none", :cache_control=>"no-cache,must-revalidate,max-age=0,no-store,private", :set_cookie=>["BrowserId=DOR6nshpQC659waq6EKS3A;Path=/;Domain=.salesforce.com;Expires=Mon, 30-Sep-2019 01:39:15 GMT;Max-Age=5184000"], :expires=>"Thu, 01 Jan 1970 00:00:00 GMT", :sforce_limit_info=>"api-usage=331/15000", :location=>"/services/data/v45.0/sobjects/Contact/0032v00002qU3hvAAC", :content_type=>"application/json;charset=UTF-8", :vary=>"Accept-Encoding", :content_encoding=>"gzip", :transfer_encoding=>"chunked"}
+  body: {"id":"0032v00002qU3hvAAC","success":true,"errors":[]}
 ```
 
 ## Structure
 
 Following is the general structure of test automation suite that uses this approach. Details may vary depending on the
\ No newline at end of file