# Current site vs Gatsby comparison ## Dev Experience ### Inner Loop Workflow #### Problem: Current website code is spread across 4 different packages (fabric-website, fabric-website-resources, office-ui-fabric-react, example-app-base) causing inner loop to be difficult to understand even for experienced fabric devs. #### Solution: Gatsby stack is fast, modern, and allows the site to consume raw assets (like markdown) rather than requiring pages to be stiched together and exported from a finished package. Gatsby also has a modern 'theming' story that allows us to create new sites based off of a template, like the existing example app base. ### Building the Site #### Problem The current site is part of the OUFR mono repo, and depends on several internal packages. This means that building and deploying the site require complete builds of our entire library. Pull requests to fix typos require change files (requiring local yarn command), and 30 minute build processes to preview. #### Solution A Gatsby based solution would be in a seperate repo therefor could have different checking/release rules, and have a sub minute build time. We can continue to consume markdown and examples from OUFR, but other documentation could be internal to the site (tutorials, dev best practices), or even in a 3rd repo (designer guidance, accessibility guidance). ### Coupled content and presentation #### Problem: Circular Dependencies. Site presentation (appearance) is spread across multiple packages and final markup is determined by a combination of all 4 layers. #### Solution: Gatsby would create a proper separation of content and presentation meaning that the site can be updated to support additional content without having to modify the content store. #### Problem: Component examples serve multiple purposes for different audiences. The same example is used for documentation, development, AND testing. The result is that our examples tend to be complex in nature, as they are used to exercise the many props combinations rather than explaining in simple illustration how to use these components. #### Solution: We clearly need to consider the audience when we create the website. The principle to follow here is "Store Front vs Workshop". For development and testing components, we should use a separate tech stack altogether (e.g. Storybook). Gatsby would allow content writers optimize their workflow instead towards creating documentation that illustrate how to use a component rather than an exhaustive combination of variants. ## Site Performance ### Site Fragility #### Problem: Current site is 100% JavaScript application which means many bugs (in Fabric or coming from MWF) cause the entire site to stop working #### Solution Gatsby is a static site generator. Even if React fails to load (and some advanced functionality stops working), the site/documentation will continue to load without a hitch. ### Speed and Pageweight #### Problem: Current site requires the entire application bundle (326kb compressed) to be loaded before a single page can be rendered. This, plus MWFs 200kb of css and js make our site very slow over anything but the fastest network and computer #### Solution: Gatsby pre-compiles every page of the site, meaning that the button page can be rendered as soon as the Button HTML and CSS reach the browser. ## Scalability ### Problem: Scaffolding new docs sites is difficult The current site bring it's own router manual boilerplate to get started can't create blank canvas (merge styles, css, fluent theme) hot module reloading out of the box - change out stuff without reloading page ## Authoring Experience ### Developer knowledge required to contribute #### Problem Current workflow requires users to know how to edit, and create pull requests for markdown files in Git repos they might not even know exist. #### Solution Gatsby is flexible enough to support multiple different content sources, so the location of the content is 100% up to the authoring team. ### Single Content Source #### Problem Current site relies on an npm package of content built and bundled up in office ui fabric react. The process of getting content onto the page is complex and requires touches up and down the chain (OUFR, example app base, fabric-site-content, fabric-site) #### Solution With Gatsby and a headless CMS like Contentful, SanityIO, or open source Strapi, writing and consuming content are completely seperate concerns. Gatsby can easily consume multiple sources of content in multiple formats. ## New Content Stuff ### Sub heading content