Internal Documentation at Scale: SPS Commerce Case Study

SPS Commerce ($SPSC) is the world’s leading retail network, connecting trading partners around the globe to optimize supply chain operations for all retail partners. It supports data-driven partnerships with innovative cloud technology, customer-obsessed service, and accessible experts so our customers can focus on what they do best. Over 50,000 recurring revenue customers in retail, grocery, distribution, supply, manufacturing, and logistics are using SPS as their retail network. SPS has achieved 98 consecutive quarters of revenue growth and is headquartered in Minneapolis.

SPS Commerce uses Fern to power their internal documentation for platform engineering, which is used by 100s of developers daily.

This article is written by Travis Gosselin, Distinguished Software Engineer focused on Developer Experience at SPS Commerce.

Growth without guardrails

SPS Commerce has long been an organization that fell into the pattern of "you build it and you run it", following the foundational principles of DevOps. Historically, our software teams had complete autonomy to drive what they needed with little technology standardization.

As SPS grew, we quickly recognized that striking the right balance between standardization and autonomy is essential to achieve consistency, scale, and speed. At the time, we didn’t call it “platform engineering,” but that’s what it would come to be known as today.

While platform engineering can mean many things to many people, we generally think of it as providing reusable tools, services, and standards to make software delivery faster, more reliable, and more secure.

Instead of every team solving infrastructure, deployment, and tooling challenges independently, platform engineering creates a shared “paved road” or “golden path” — a standardized set of workflows, APIs, and environments that developers can use to ship code with minimal friction. We viewed this as having five key elements: application configuration management, infrastructure orchestration, environment management, deployment management, and Role-Based Access Control.

‍

The goal is to strike a balance between autonomy (so teams still own their services) and standardization (so teams don’t reinvent the wheel), ultimately improving productivity, reducing operational risk, and accelerating delivery. The vehicle to deliver such goals we think of as our ‘Internal Developer Platform’.

Why we needed internal documentation  

While SPS Commerce had long practiced a forms of an internal developer platform to support teams, we formally productized our approach in 2020. However, we placed a much smaller amount of effort and emphasis on what we have come to learn now is one of the most critical pieces of any platform: documentation.

Looking back, it is really silly, of course, but when it's not a muscle you’re used to exercising, and so much knowledge transitions between teams via tribal knowledge, it's not always front-of-mind.

As our platform usage grew, features expanded, and developers got burnt often by:

• Poor discoverability: The most common way to discover features was asking someone over a Slack request, which not only inundated developers with requests, but also took away time from actually shipping code.
• Inconsistent documentation standards: Various bits of knowledge were documented across many sources, including Confluence, GitHub README, SharePoint, and Slack. The discoverability was hard, but also the inconsistency of format made it hard to follow between different docs (if at all).
• Duplication and drift: Documentation would become stale fast without a single source to discover gaps and assigned owners for each update.
• Slowed developer onboarding: Without a single location for documentation, new hires didn’t know what data silos to sift through.
• Redundant development: We found that developers would try to build first rather than find first, resulting in time lost on duplicated efforts.

In short order, we found that internal documentation is the glue that holds platform engineering together as a rally point, solving many of the pain points above.

How we approached internal documentation

Step #1: Building our first version  

Upon the realization that documentation and knowledge management were far more important than we previously realized, especially for a company growing and doubling its developer teams in size, we began to standardize and centralize.

All documentation related to our internal development platform was centralized into a single asset that was published at a single easy-to-find URL. This solved a number of pain points and offered several benefits:

• Centrally accessible documentation: We provided a single accessible URL. This was built with GitHub Pages and a Jekyll theme. This made the infrastructure fast and cheap, while authorization was handled automatically with GitHub permissions (i.e. as part of our organization). Having all the content centralized and searchable in a single spot also meant we could much more easily identify gaps, inconsistencies, and find the content we wanted much faster!
• Docs-as-code: Treating documentation-as-code was essential in establishing it as a first-class citizen among our engineers. We didn't have dedicated technical writers for internal documentation. As such, having docs-as-code and keeping it as close to the related content was important for engineers to foster easy documentation updates right along their source code.
• Remote content updated nightly: We found it was important not to centralize all documentation into a disconnected repository, removed from the teams and systems that created it. With docs-as-code, we could pull content centrally each night and publish it to the core site, ensuring visibility and consistency while keeping ownership firmly with the teams responsible.

This initial solution solved our pain point: developers now had a single place to turn to for questions. We found this made a huge difference in reducing friction, improving knowledge sharing, and speeding up onboarding for new engineers. Questions that previously took hours—or required tapping multiple teammates—could now be answered in minutes. Teams were more consistent in their approaches, duplicate efforts were reduced, and engineers felt more confident that they were working with the most accurate, up-to-date information.

While this was a great first step, we realized we would need additional modernization. Specifically, with the amount of documentation we were building, the GitHub Pages site and build process severely degraded over time. Build times sky-rocketed, teams stopped building and running docs locally for changes. Security warnings and requirements slowly crept up. We needed something better.

Step #2: Using Fern to focus on enterprise performance at scale

When taking a step back and looking at our performance challenges, we realized we needed an enterprise solution that would offer all the benefits of great technical documentation with little overhead for both builders and producers of the content.

We did an evaluation of many documentation players and quickly realized that Fern had a lot of pieces to make for a fantastic internal documentation experience.

We migrated (via a synchronization process) the content of our old developer documentation. Fern made this straightforward and easy given they have a simple CLI tool that works cross-platform easily on any CI system. The benefits were massive:

• Build speed was 20x faster: What took a significant amount of resources before on GitHub Pages now builds 20x faster with Fern. With 100’s of pages of documentation, API specs, and external content, we are able to build our documentation in seconds both locally and during continuous integration.
• Preview URLs make content consistent: With preview URLs we can easily orchestrate preview versions of the site directly in remote content. Rather than pull content in nightly, we orchestrated push validation and preview URLs to provide immediate feedback.
• AI-enabled search: Our search experience before didn't work well, and struggled with semantics. In some cases, teams would think a feature didn't exist (even those on the platform engineering team) and start writing it, not realizing the search didn't find it prior. Fern provides best-in-class search indexing and AI-enabled search, Ask Fern, out of the box. With AI-enabled search, our developers have a ‘Cursor-like’ chatbot that they can interact with directly in our documentation.
• Long-term partner: Most important is that Fern is a long-term partner for our documentation experience that we can rely on to ensure we can focus on actually building our platform and not the documentation infrastructure.

Six considerations when building your internal docs:

We are just rolling Fern out now to a broader developer audience to standardize all technical documentation. In the industry in general, I think the approach and skillset among teams for internal documentation is going to need to step up its maturity, especially in an age of AI, where you cannot take the elimination of tribal knowledge for granted. Some key considerations and best practices we discovered in our approach:

1. Your internal developer platform is a product: We've been told to treat our internal developer platform like a product for years. If you haven't started doing it, then now is the time, and any great product has great documentation. As much as you like to think it's "self-documenting", it’s not! A knowledge management strategy is critical for any platform engineering team.
2. Docs-as-code is critical: Treating your docs like a first-class citizen demonstrates you care about it and that you apply the same rigor, maintenance, and curation on it as the code itself. Ideally, when adding a new feature, teams can include updates, changes to docs right in the same PR to consider it ‘done’ (put it in the team working agreement).
3. Docs should be owned by many teams: While the infrastructure for docs may be owned by a single team, when an organization is large enough, documentation is contributed by many teams. Clearly identifying and even codifying those owners is important for the longevity and care of the knowledge. We include clear GitHub Code Owners as part of contributing documentation.
4. Be extensive with your documentation: As Divio guidance puts it: "There is a secret that needs to be understood in order to write good software documentation: there isn't one thing called documentation, there are four." Consider what your tutorials, how-to guides, explanations, and references are. You are not done if you're not focusing on the different orientations of access for that material. This may be a good guide to help you organize the navigation and ongoing challenges around bringing together such a wide set of content effectively.
5. Document what matters: Documentation on “What is Kubernetes” adds little value to your organization. While it can help onboard junior engineers, that information is widely available elsewhere. The real impact comes from documenting what’s unique to your organization—how you use Kubernetes, the abstractions you’ve built, and what makes your implementation different.
6. Creating a centralized golden repository for AI is foundational: In an age of AI, where tribal knowledge is a productivity killer for your agent, you need to work to build your golden repository of knowledge, best practices, and approaches not just for the humans in your enterprise but also for the machines. Exposing a good search index against an MCP server means your organizational coding and background agents now have the context they need to develop something not with industry best practices, but with your own best practices.

Great platform engineering needs great documentation

SPS Commerce’s journey from fragmented tribal knowledge to a highly-performant, AI-enabled internal documentation platform illustrates a simple truth: great platform engineering cannot thrive without great documentation. By centralizing knowledge, adopting a docs-as-code approach, and partnering with Fern to deliver performance and search at scale, we’ve transformed how 100s of developers discover, learn, and build on our internal platform.

‍