Building the WeSalute Open Site

Howdy, it's not often we get to launch a new website, and I wanted to take this opportunity to share the background and technical steps towards the development of WeSalute Open.

Problem Statement: Building the content for a consistent and scalable company handbook is hard. Delivering it to all team members, in a digestible and organized format is hard. Figuring it out is a requirement to scaling an organization and creating a effortless Team Member Experience.

This blog post continues with Read More...

Requirements: We knew that having a single PDF wasn't scablable. The moment we made an update or a new release to the WeSalute Open Handbook a new version would have to be generated. We wanted to provide an experience for new and existing team members. As a result we settled on the following goals in the form of requirements:

• A canonical source of truth, a resource everyone in the company could point to and lean on
• digestible, the content had to be easily navigated, referenced, and ideally searchable
• maintainable, content had to be structured and easy to work with, such as metadata
• changelog, we needed to commmunciate the lifecycle of the WeSalute Open Handbook, including structured and unstructured changes
• an immutable destination, WeSalute Open content needed to be citable via links, such as in the spirit of reference numbers...
• productiziation, WeSalute Open must be a product that the company can deliver to itself and it's team members, WeSalute Open would be WeSalute's face
• syndication, we needed to get WeSalute Open into as many touchpoints of the Team Member Experience as possible, we're better when we're all aligned
• interactivity, WeSalute Open needed to collect anonymous feedback and perform product-led growth, listening to and growing as a product for WeSalute Team Members, we needed an application
• branded, in alignment with the WeSalute Design Systems, if WeSalute Open was a product, it needed to be in compliance with the WeSalute experience. Colors, images, fonts, etc.

Previous Work and Attempts: Progress is progress, and previously we had created a Google Doc, that evolved in a series of Confluence documents, which would be syndicated to each team's confluence space. We found that Confluenecs ability to handle this much content as scale, along with macros needed to create the metadata and interactivity, resulted in a slow and difficult to absorb content. To address this content started getting slimmed down, resulting in an anti-pattern of growth, as a result we needed a different solution. We were not delivering on our goals for authors, maintainers, and team members alike.

New Opportunities: The landscape changed, and there were a few development that aligned allowing us to identify a new solution. The star's aligned so to say:

• Meta Open Source Releases Docusaurs 3.0 on October 31, 2023, a massive improvement in their static site documentation generator, now supporting Typescript and additional features in alignment with our requirements
• We formed a direct relationship with Cloudflare, providing reliabile enterprise access to Cloudflare Pages and Workers
• We rebrand as WeSalute, now we can lean into the WeSalute brand, making the time-effort-value relationship worth it to build a website
• We subscribe to GitHub Codespaces, providing a zero-setup developer experience for writing content and developing the codebase
• We subscribe to Algolia, providing an enterprise-grade search functionality
• We adopt Cloudflare Access across the organization thanks to Systems and Engineering Operations, providing the ability to publish internet exposed assets but limit the audience to authenicated WeSalute Team Members

Results: With all the market conditions teed up for us. We were able to release open.wesalute.com using our existing infrastructure. No need to re-invest the wheel. Yeehaw!

Deployment Workflow:

• The code, in the form of javascript and typescript, and the content, in the form of markdown, lives in GitHub under the wesalute-open repository.
• Deployments to the production branch of wesalute-open automatically trigger a build of the site, and are deployed to Cloudflare Pages via Cloudflare Workers, from the my-docusaurus-app folder
• Cloudflare Access then protects the domain and sub-directories, limiting the audience who can view to page to authenicated WeSalute Team Members

Developer Workflow:

• visit the wesalute-open repository in GitHub
• open a GitHub codespace for wesalute-open
• in the vscode terminal run the command, npm run pages:dev to get a live local preview of the site in real time, great for seeing if you break anything! The local build is continously complied by webpack and delivered to port 3000
• write code and/or markdown in the respective folders
• changes that are then commited are automatically deployed to production

Exploring the Codebase:

• if you have access to the WeSalute org on GitHub, just type vscode.dev/<repositoryUrl> prior to the repo url, check it out here

Thank you! Delivering open.wesalute.com has been a pleasure. It truly represents a step forwards towards a better Team Member Experience. It is us, our team, who delivers our on the WeSalute mission. WeSalute Open is a small step forward to scaling our efforts to deliver value to those that serve.