some more edits

Author: i8ramin

Diff for: _drafts/wework-com-is-going-static.markdown

@@ -2,30 +2,30 @@
 layout:       post
 title:        WeWork.com is Going Static
 author:       ramin_bozorgzadeh
-summary:      Back when the web first started, things were a lot more simple. Most websites were made up of static html pages and not a lot of moving parts. A lot has changed since then, but ever present desire to "keep it simple" is still there. This is the story of how wework.com went from a complicated "web app" to a basic statically generated site and why ...
+summary:      Back when the web first started, things were a lot simpler. Most websites were made up of static html pages and there weren't a lot of moving parts. This is the story of how wework.com went from a full-stack "web app" to a statically generated site, and why ...
 image:        //res.cloudinary.com/wework/image/upload/c_fill,f_auto,g_faces,h_800,w_1000/v1448734984/engineering/wework-com-is-going-static.jpg
 categories:   engineering
 ---
 
 ### What is this "static" business all about?
 
 Static site generators have become a hot topic in the past few years. There are [whole sites](https://www.staticgen.com/) dedicated to tracking and rating them. Don't take my word
-for it, check out this graph from [Google Trends on "static site generator"][2]:
+for it, check out this graph from [Google Trends for "static site generator"][2]:
 
 [![Google Trends - Static Site Generator][1]][2]
 [1]: //res.cloudinary.com/wework/image/upload/f_auto/v1448735896/engineering/static-site-generator.png
 [2]: https://www.google.com/trends/explore#q=static%20site%20generator
 
 The idea is actually quite simple. Whereas on a traditional *dynamic* site, each page is proceed and generated on the server per request (let's ignore caching strategies for the sake of argument), a static site is processed and generated just **once** on each deploy and all the server has to do is serve up the resulting generated HTML. Of course, this is an overly simplified explantion of how it all works, and this process doesn't work on all web sites, but it does work really well for marketing and informational sites like wework.com. This very blog you are reading is actually a statically generated site using [Jekyll](http://jekyllrb.com/) and hosted on [Github pages](https://pages.github.com/)!
 
-If you consider the amount of information that changes on a daily, or even weekly basis on a site like wework.com, it is actually very wasteful to have a server process each and every request that comes through. One of the main reasons we even have a server-side component is to allow us to easily add new information to the site, manage the content that is being served up and build administrative dashboards that allow a non-developer to update this information. The great news is, we can still achieve all of this with an API and take the load off of our application server for serving up these mostly static HTML pages.
+If you consider the amount of information that changes on a daily, or even weekly basis on a site like wework.com, it is actually quite wasteful to have a server process each and every request that comes through. One of the main reasons we even have a server-side component for wework.com is to allow us to easily add, update and manage information on the site. We can still achieve this with a statically generated site by utilizing an API to serve up the data and take the load off of our application server for serving up the html pages themselves.
 
 
 ### The static / dynamic hybrid approach
 
-One key requirement for us when evaluating different static site generators was the ability to hit an API endpoint for data, and dynamically generate static pages based on this data. A real-world example of this is when we add new locations and markets. With a traditional web-app setup (like a Ruby on Rails project), as soon as you add a new location or update one, the new content is up and live on your website. With a statically generated site, this is not the case. You will need to rebuild the entire site and generate the new HTML. The good news is, for a site that doesn't have a ton of content, this static site generation is actually really fast. Like in the tens of seconds fast. A couple of minutes if you consider the entire proecss of minifying assets and deploying of the site.
+One key requirement for us when evaluating different static site generators was the ability to hit an API endpoint and dynamically generate static pages based on the data returned. A real-world example of this is when we add new locations and markets. With a traditional web-app setup (like a Ruby on Rails project), as soon as you add a new location or update one, the new content is up and live on your website. With a statically generated site, this is not the case. You will need to rebuild the entire site and generate new HTML. The good news is, for a site that doesn't have a ton of content, this static site generation is actually really fast. Like in the tens of seconds fast. A couple of minutes if you consider the entire proecss of minifying assets, building and deploying your site.
 
-We played with and evaluated quite a few options, like pure jekyll, yeoman, Middleman, etc. The one we decided to go with is a very well thought out static site generator called [**Roots**](http://roots.cx/), developed by the fine folks at the Brooklyn based agency, [Carrot Creative](https://carrot.is/). Besides the many nice features that Roots gives you right out of the box (folder structure, asset management and minifcation, etc), they also have a really nifty extension called [**roots-records**](https://github.com/carrot/roots-records). Like most well built things, roots-records serves one purpose and does an amazing job at it. It allows you to hit ANY endpoint that returns a JSON collection and use that collection in your templates to iterate over or if you pass in a template, it will also generate individual static HTML pages for each item in the collection. For example, here is all we had to define in our `app.coffee` file to hit our API endpoing for our market/location:
+We played with and evaluated quite a few options, like pure jekyll, yeoman, Middleman, etc. The one we decided to go with is a very well thought out static site generator called [**Roots**](http://roots.cx/), developed by the fine folks at the Brooklyn based agency, [Carrot Creative](https://carrot.is/). Besides the many nice features that Roots gives you right out of the box (folder structure, asset management and minifcation, great extension and plugin system, etc), they also have a really nifty extension called [**roots-records**](https://github.com/carrot/roots-records). Like most well built things, roots-records serves one purpose and does an amazing job at it. It allows you to hit ANY endpoint that returns a JSON collection and use that collection in your templates to iterate over or if you pass in a template, it will also generate individual static HTML pages for each item in the collection. For example, here is all we had to define in our `app.coffee` file to hit our API endpoing for our market/location:
 
 ```coffeescript
 extensions: [
@@ -49,35 +49,62 @@ each countries, index in records.marketsByCountry
         != countries[0]
 ```
 
+Once we are ready to move our individual location pages over to *static*, all we need to do is pass a `template` option to the `records` block in our app.coffee config, and Roots will generate the individual location pages when it builds the site. This would look something like this:
+
+```coffeescript
+extensions: [
+  records(
+    marketsByCountry: {
+      url:
+        path: "#{process.env.DUBS_API}/api/v1/locations/markets_by_country"
+        headers: { Authorization: "Token token=#{process.env.DUBS_API_TOKEN}" }
+      template: "views/_location.jade"
+      out: (location) -> "/locations/#{location.market.slug}/#{location.slug}"
+    }
+  )
+]
+```
+
 
 ### The static host with the most
 
-One of the biggest challenges of this whole process has been to figure out a way to slowly migrate our site over from a dynamic app, over to a static one. One way to do this would be to stop all development for a few months and rebuild all of our pages one by one over to this new infrastructure. But as the saying goes, "aint nobody got time for that!"
+One of the biggest challenges of this whole process has been to figure out a way to slowly migrate our site over from a dynamic app, over to a static one. One way to do this would be to stop all development for a few months and rebuild the entire site using this new infrastructure. But as the saying goes, "ain't nobody got time for that."
 
 We needed a way to move things over piecemeal. One page at a time. This meant that we couldn't move wework.com to a new static host all at once, but at the same time, we needed some URL's to serve up the old content, and some URL's to serve up the new static pages. One way to do this is via a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy).
 
 There are many different ways to skin this cat. You can install and configure your own Apache or Ngnix server. You can use something like [`rack-reverse-proxy`](https://github.com/jaswope/rack-reverse-proxy) or a slew of other similar solutions. There are pros and cons to each approach. For us, being a team of web developers, we wanted to spend our time focusing on our KPI's and optimizing our pages for performance, and not on setting up and managing servers. We had a few requirements. Specifically, we were looking for a host that could:
 
-- House our new static site and scale with our fast growing company
-- Have an API so we can trigger builds when content changes
+- House our new static site and scale with us
+- Have an API and webhooks so we can trigger builds when content changes
 - Ability to proxy requests to other URL's (internal and external)
 - Global CDN to improve our international traffic and SEO
 - Easy to use and configure
 - Great and responsive customer support
 
 We found one host that met all of those requirements and more, and they are called [Netlify](https://www.netlify.com/). Never heard of them? Neither had we, but as one engineer I recently spoke with who was familiar with their services put it, "Netlify is like the developer whisperer". This team has put together an amazing service that handles SO much for you from a dev-ops persective of hosting static sites. And if there is a feature that is missing, they will bend over backwards to either implement it for you, or help you figure out a solution. I can sit here and sing their praises all day long, but its probably best if I explained a bit about how they were able to help us with our migration to a static site and make the static verions of our site *2-3x faster*.
 
-To get started, one of the first pages we decided to migrate over to static was our [`/locations`](https://www.wework.com/locations/) page. This page doesn't get a ton of traffic, but has dynamic content coming from our backend, so it seemed like a good place to start. We no longer have the old version up now, so I can't do a side by side comparison, but just looking at the graph below you can see the downward trend from the day we rolled it out. Our server response time is **1ms** (this number is around 150-200ms on other pages) and the page is visually complete in about 2.8 seconds, which is 2-3x faster than it used to be. Of course, we've done other optimizations as well (reducing unused assets, optimizing images, etc) and there are still other things we can do to make it even more performant, but we are very pleased with the results so far.
+To get started, one of the first pages we decided to migrate over to static was our [`/locations`](https://www.wework.com/locations/) page. This page doesn't get a ton of traffic, but has dynamic content coming from our backend, so it seemed like a good place to start. We no longer have the old version up now, so I can't do a side by side comparison, but just looking at the graph below you can see the downward trend (in the world of performance, downward trending graphs are usually a good thing) from the day we rolled it out. Our server response time is **1ms** (this number is around 150-200ms on other, non-static pages) and the page is visually complete in about 2.8 seconds, which is 2-3x faster than it used to be. Of course, we've done other optimizations as well (reducing unused assets, optimizing images, etc) and there are still other things we can do to make it even more performant, but we are very pleased with the results so far.
 
 ![Performance graph of locations page](http://res.cloudinary.com/wework/image/upload/c_scale,f_auto,w_1000/v1448740493/engineering/locations-graph.png)
 
-So how are we serving up traffic to `wework.com/locations/` from the static host and the other pages from our current host? It was as simple has modiftying some DNS settings to route all traffic through Netlify, [creating a `_redirects` file](https://www.netlify.com/docs/redirects) at the root of our very basic static site and configuring Netlify to compile and deploy our static site anytime it detects changes in our `master` branch.
+So how are we serving up traffic to `wework.com/locations/` from the static host and other pages from our current non-static host? It was as simple has modiftying some DNS settings to route all traffic through Netlify, [creating a `_redirects` file](https://www.netlify.com/docs/redirects) at the root of our very basic static site, with some rules about which URL's to pass through and which ones to handle. Netlify's proxy and rewrite is actually very intelligent in how it handles requests. If it finds the file, folder or resource locally in your folder structure, it will serve that up before it tries to proxy it. On our site, we have a catch-all rule that looks like this:
+
+```coffeescript
+extensions: [
+  netlify
+    rewrites:
+      '/':  dubsUrl
+      '/*':  dubsUrl + '/:splat'
+```
+
+Which basically says, route all traffic through to `dubsUrl`, which is defined further up using `ENV` variables. We never have to touch this rule, and as soon as we added the `/locations/index.html` resource to our static site, Netlify was smart enough to serve that page vs proxying it through.
+
 
 The reality is that we are currently maintaining two versions of our site as we move things over, but this allows us to continue doing business as usual, make updates to existing pages and not have to stop our normal workflow as we migrate things over little by little. What's great about all of this is that we are sharing the same data across both sites.
 
-By doing this, we hope to see an improvement in direct and SEO traffic and hopefully a small uptick in our KPI numbers, as it has been proven that conversion numbers generally improve when your pages load faster and people are able to get to the information they are looking for quicker. This also allows us to expand globally without having to worry as much about traffic load and performance. One thing to keep in mind with all of this is that it is not necessarily *easier*, but it is a lot *simpler*. And as a side effect of serving up static pages, your site becomes a lot more secure. There is a [great article on Smashing Magazine](http://www.smashingmagazine.com/2015/11/modern-static-website-generators-next-big-thing/) written by the co-founder of Netlify (Mathias Biilmann Christensen) about why static site generators are the next big thing. If you are interested in this approach, I highly recommend reading it.
+By doing this, we hope to see an improvement in direct and SEO traffic and hopefully a small uptick in our KPI numbers, as it has been proven that conversion numbers generally improve when your pages load faster and people are able to get to the information they are looking for quicker. This also allows us to expand globally without having to worry as much about traffic load and performance. One thing to keep in mind with all of this is that it is not necessarily *easier*, but it is a lot *simpler*. Also as a side effect of serving up static pages, your site becomes a lot more secure. There is a [great article on Smashing Magazine](http://www.smashingmagazine.com/2015/11/modern-static-website-generators-next-big-thing/) written by the co-founder of Netlify (Mathias Biilmann Christensen) about why static site generators are the next big thing. I highly recommend checking it out.
 
-In a future post we will discuss how we've started to also generate our React components as part of this static build process and how by doing so, we've seen a huge improvement in overall load times on pages that rely heavily on React.
+In a future post we will discuss how we've begun a journey into [**Isomorphic or Universal Javascript**](http://techblog.netflix.com/2015/08/making-netflixcom-faster.html) by generating our React components as part of this static build process.