Aux Eng Playbook

A playbook for technologists interested in introducing Auxiliary Engineering to their engineering organization. The Aux Eng Playbook aims to document Wayfair Tech's pioneering implementation of Aux Eng programs while sharing key takeaways, learnings, and recipes for success.

🚀 Quick Start

To get started editing this site, you'll need Node v14+, and preferably v19. We recommend using nvm.

Once that's installed, you'll need yarn as well.

Start developing by initializing your node modules:

yarn

Then start the gatsby development server:

yarn build
yarn develop

Plenty of information may show, but you should eventually see something like:

You can now view Aux Eng Playbook in the browser.

  http://localhost:8000/

You can edit the site by editing the files in src/. This site uses CSS, JS, and css-in-js.

💡 Note that for most images, you'll want to run yarn build before they show up correctly on the development site.

🐳 Docker Setup

If you'd prefer to develop within a node:19-alpine container, this project also supports using Docker Compose with hot-reloading capabilites for Gatsby.

First, make sure you have both docker and docker-compose installed.

To bring up the gastby development server, run:

docker-compose down
docker-compose up -d develop # Remove the -d flag if you don't witsh to daemonize the container

Once the server is up and running, when you make local changes to your gatsby site content, the changes should hot-reload in your containerized instance, accessible in a browser at http://localhost:8000. Note that it's easier to observe the hot-reloading functionality in action when the container is not daemonized.

If you'd like to interact with the gatsby-cli directly, you can also run commands like:

docker-compose run gatsby --help
docker-compose run gatsby info # Example commmand to get environment information for debugging

Contributing to Docs

If you're here to write some of our plentiful documentation, use these foolproof steps:

1. Ensure you've completed the Quick Start above, and have a server running.
2. Make a new branch for your new document post.
3. Create a new directory (or sub-directory, or sub-sub-directory) in src/docs like my-doc
4. Create an index.md file in src/docs/my-doc (or whatever you named your doc). This will be your document's markdown page.
5. Write the frontmatter for the page like so:

---
title: "My Snazzy Article"
---

1. Optionally, include any assets you need (images, etc) alongside index.md, and reference them directly, eg: [my-image](./my-image)
2. Watch your markdown come to life in your browser by visiting the corresponding path to your document from /docs (in this case, we'd visit docs/my-doc)
3. When satisfied, commit the result for review.

Deploying

As long as permissions work and everything is aligned in the stars, you ought to be able to deploy with:

yarn deploy

Troubleshooting

If you see strange behavior from developing or building the app, try npx gatsby clean. This should use the gatsby-cli to clean out frayed node modules or other unexpected hitches.