squash: add some docs

helpers/sql/README.md

@@ -14,7 +14,25 @@ Or, if you use [bundler][bundler-home], include `opentelemetry-helpers-sql` in y
 
 ## Usage
 
-## Examples
+This gem is intended to be used by the instrumentation libraries to provide a common set of helpers for SQL-related spans. It is not intended to be used directly by applications.
+
+Some Database libraries do not have enough context to add sufficient details to client spans. In these cases, you can use the `OpenTelemetry::Helpers::Sql.with_attributes` to create a set of shared attributes to amend to a database span.
+
+```ruby
+# Higher-level instrumentation e.g. ORM
+OpenTelemetry::Helpers::Sql.with_attributes({ 'code.namespace' => 'Acme::Customer', 'code.function' => 'truncate!', 'db.operation.name' => 'TRUNCATE', 'db.namespace' => 'customers' }) do
+  client.query('TRUNCATE customers')
+end
+
+# Client snippet
+class OtherSqlClient
+  def query(sql)
+    tracer.in_span("query", attributes: OpenTelemetry::Helpers::Sql.attributes.merge('db.statement' => sql, 'db.system' => 'other_sql')) do
+      connection.query(sql)
+    end
+  end
+end
+```
 
 ## How can I get involved?