start to fill in more migration docs

diff --git a/docs/migration.md b/docs/migration.md
index a03be5dea66ac55716105a42d08746acafb68135..f699cdc3c9eaf0110403842be3a1951de2f7e06a 100644 (file)
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -3,40 +3,58 @@ layout: page
 title: Migrating to v4.x.x
 ---
 
+Bootstrap 4 is a major rewrite of almost the entire project. The most notable changes are summarized immediately below, followed by more specific class and behavioral changes to relevant components.
+
 ## Summary
 
-For a broader overview, see [what's new](http://blog.getbootstrap.com/DEAD-LINK-FIX-ME-PLEASE) in the v4.0.0 release announcement.
+Here are the big ticket items you'll want to be aware of when moving from v3 to v4.
 
-- Dropped IE8 support—v4 is now only IE9+. For sites needing IE8, use v3.
-- Dropped iOS 6 support.
+- Dropped IE8 and iOS 6 support. v4 is now only IE9+ and iOS 7+. For sites needing either of those, use v3.
 - Added official support for Android v5.0 Lollipop's Browser and WebView. Earlier versions of the Android Browser and WebView remain only unofficially supported.
-- Switched from `px` to `rem` as our primary unit in CSS.
-- Media queries are now in `em`s.
+- Switched from `px` to `rem` as our primary CSS unit.
+- Media queries are now in `em`s instead of `px`s.
 - Global font-size increased from `14px` to `16px`.
-- Dropped panels, thumbnails, and wells for a new component, cards.
+- Dropped panels, thumbnails, and wells for a new all-encompassing component, cards.
 - Switched from LESS to SCSS for our source CSS files.
 - Added a new grid tier for ~`480px` and below.
-- Dropped Glyphicons icon font.
+- Dropped the Glyphicons icon font.
 - Dropped the Affix jQuery plugin. We recommend using a `position: sticky` polyfill instead. [See the HTML5 Please entry](http://html5please.com/#sticky) for details and specific polyfill recommendations.
 - Refactored nearly all components to use more unnested classes instead of children selectors.
 - Non-responsive usage of Bootstrap is no longer supported.
+- Images are now responsive (via `max-width`) by default.
 - Dropped the online Customizer in favor of more extensive setup documentation.
-- Replaced the separate optional theme with...
+- Replaced the separate optional theme with configurable options via SCSS variables (e.g., `@enable-gradients: true`).
 
-## Major class changes
+## By component
 
 This table shows the style changes between v3.x.x and v4.0.0.
 
-| Bootstrap 3.x.x | Bootstrap 4.0.0 |
-| --- | --- |
-| Pager's `.previous` | `.pager-prev` |
-| Pager's `.next` | `.pager-next` |
-| Carousel's `.item` | `.carousel-item` |
-| Tabs | |
-| Pills | |
-| Buttons | |
+### Tables
+
+- Nearly all instances of the `>` selector have been removed, meaning nested tables will now automatically inherit styles from their parents. This greatly simplifies our selectors and potential customizations.
+- Responsive tables no longer require a wrapping element. Instead, just put the `.table-responsive` right on the `<table>`.
+- Changed `.table-condensed` to `.table-sm` for consistency.
+- Added a new `.table-inverse` option.
+
+### Pager
+
+- Changed `.previous` and `.next` to `.pager-prev` and `.pager-next`.
+
+### Carousel
+
+- Changed `.item` to `.carousel-item`.
+
+## Documentation
+
+Our documentation has received an upgrade across the board as well. Here's the low down:
+
+- We're still using Jekyll, but we've got a custom plugin in the mix (`example.rb`) for easier example-code handling.
+- All docs content has been rewritten in Markdown (instead of HTML) for easier editing.
+- Pages have been reorganized for simpler content and a more approachable hierarchy.
+- We moved from regular CSS to SCSS to take full advantage of Bootstrap's variables, mixins, and more.
 
 ## What's new
+
 We've added new components and changed some existing ones. Here are the new or updated styles.
 
 | Component | Description |
@@ -61,7 +79,10 @@ The following components have been removed in v4.0.0.
 
 TODO: audit classes in v4 that aren't present in v4
 
+### Responsive utilities
+
 The following deprecated Less/SCSS variables have been removed in v4.0.0:
+
 * `@screen-phone`, `@screen-tablet`, `@screen-desktop`, `@screen-lg-desktop`. Use the more abstract `$screen-{xs,sm,md,lg,xl}-*` variables instead.
 * `@screen-sm`, `@screen-md`, `@screen-lg`. Use the more clearly named `$screen-{xs,sm,md,lg,xl}-min` variables instead.
 * `@screen-xs`, `@screen-xs-min`. The extra small breakpoint has no lower bound, so these variables were logically absurd. Reformulate your expression in terms of `$screen-xs-max` instead.