More updates

website/docs/intro.md

@@ -6,36 +6,58 @@ slug: /
 
 Mobility is a **framework** for **translating model data**. There are many
 other gems out there that can help you store translated data[^1], but Mobility is
-different. While other gems prescribe _how_ to store your translations,
-Mobility separates the **storage** of translation data from the **use and
-manipulation** of translation data. This separation makes code cleaner, more
-powerful, and easier to reuse.
+different. While other gems prescribe how to store your translations
+and what features to offer for retrieving those translations, Mobility leaves
+these choices up to you.
+
+Mobility can do this thanks to a separation
+between the **storage** of translation data ([backends](backends)) and the **use and manipulation** of
+that data ([plugins](plugins)). This separation makes code cleaner, more powerful, and
+easier to reuse.
 
 These docs will guide you to integrating Mobility into your application and
 provide some insights into the thinking behind its design. To get started right
 away with Mobility, jump directly to the [Installation](installation) section.
+For more background, read on.
 
 ## Why the name?
 
-So first: why on Earth is it called "Mobility"?
+So first: why on _Earth_ is it called “Mobility”?
+
+Mobility is a gem for translating content. The word “translation”
+has multiple meanings:
+
+> **translation** (_noun_):
+> 1. a rendering from one language into another
+> 2. uniform motion of a body in a straight line
+
+Given that the term for these two meanings overlaps, it is perhaps not
+surprising that many imagine translation to be a simple mapping
+(along a straight line, if you will) of words from one language to another. In
+reality, as any translator will tell you, translation is actually an incredibly
+challenging and complex process.
+
+The same can be said of _storing translations_, which can be more complicated
+than one might think. Unfortunately, this only becomes apparent long after code
+has been written and deployed. This commonly results in complex, fragile legacy
+code coupled to a particular data format, with little room for change or
+improvement.
+
+> **mobility** (_noun_): the state of being movable or having the capacity to move
 
-The act of translation may seem simple, but ask any translator and you will
-learn that it is in fact an incredibly challenging process.
-The same
-can be said of the process of _storing translations_. Unfortunately, this only
-becomes apparent long after code has already been written and deployed. This
-can result in complex legacy
-code coupled to a particular data format, with little room for improvement.
+Mobility's purpose is to break this stranglehold on translation data and
+give it the capacity to _move_. Similar to how Object Relational Mappers
+(ORMs) create a separation between objects and their data, Mobility creates
+a separation between the storage of translation data and the use of that data.
 
-Mobility's philosophy, similar to that of an Object Relational Mapper (ORM), is
-to create a separation between the storage of data and the use (reading, writing,
-and querying) of that data. By doing so, translation features that are common
-across different applications can be developed, shared and refined in isolation
-from the code used to store those translations. This makes code easier to change.
+By doing so, translation features that are common across different applications
+can be developed, shared and refined in isolation from the code used to store
+those translations. This makes code easier to understand, modify, and improve.
 
 ## Minimalism
 
-> I just want to translate these columns on this one model. I don't need a freaking framework for that!
+> I just want to translate these columns on this one model. I don't need
+> a freaking framework for that!
 
 This is an understandable gut reaction, but it is a misunderstanding of what
 the word "framework" actually means.[^2] Mobility is built as a framework in

website/src/css/custom.css

@@ -58,6 +58,6 @@ section {
   font-size: 80%;
 }
 
-article blockquote p {
-  font-size: 85%;
+article blockquote {
+  font-size: 90%;
 }

website/src/pages/index.js

@@ -27,7 +27,7 @@ function Demo() {
   return md.render(`
 ## I18n for Model Data
 
-Choose a [backend](docs/backends) to store your translations and specify your ORM as well as any other [plugins](docs/plugins) to include:
+Choose a [backend](docs/backends) and ORM to store your translations and any other [plugins](docs/plugins) to include:
 
 \`\`\`rb
 Mobility.configure do
@@ -57,10 +57,8 @@ post = Post.new(
   title: "Introduction to Mobility",
   subtitle: "Translating Model Data is Easy"
 )
-post.title
-#=> "Mobility"
-post.subtitle
-#=> "Translating Model Data is Easy"
+post.title    #=> "Mobility"
+post.subtitle #=> "Translating Model Data is Easy"
 post.save
 \`\`\`
 
@@ -71,12 +69,18 @@ Mobility.with_locale(:ja) do
   post.title = "Mobilityの紹介"
   post.subtitle = "モデルデータの翻訳は簡単"
 end
+\`\`\`
 
-post.title
-#=> "Mobilityの紹介"
+Retrieve them:
+
+\`\`\`rb
+Mobility.locale = :en
+post.title    #=> "Mobility"
+post.subtitle #=> "Translating Model Data is Easy"
 
-post.subtitle
-#=> "モデルデータの翻訳を簡単に"
+Mobility.locale = :ja
+post.title    #=> "Mobilityの紹介"
+post.subtitle #=> "モデルデータの翻訳は簡単"
 \`\`\`