Linear Docs Teardown: What's Worth Copying and What Isn't

Open linear.app/docs and the first thing you notice is what isn't there. No hero banner. No AI chat bubble in the corner. No "What's new" feed trying to sell you the current quarter's roadmap. It's a hub page with two sections, Popular and Linear basics, each rendered as a plain card grid, with the sidebar parked on the left and a simple search at the top. My one-line verdict: Linear's product docs are the cleanest B2B docs site I've navigated this year, and they do a few quietly clever things that most teams won't notice until they try to copy the look and can't figure out why theirs feels busier.

I've spent the past couple of weeks poking at Linear's docs while writing the Stripe API docs teardown and the Vercel docs teardown, and the contrast is worth writing up. Stripe and Vercel are developer platforms. Linear is a product docs site for a tool humans use every day. Most SaaS docs sit in Linear's category, not Stripe's, and Linear is where the more relevant lessons live.

What follows is the specific stuff: pages, patterns, and one or two decisions I think they got wrong.

The card-based hub page is load-bearing

The docs home at linear.app/docs is basically two sections of cards. "Popular" shows seven or eight entries like Start guide, Projects, Triage, GitHub integration. "Linear basics" fans out to the foundational areas: Teams, Issues, Issue properties, Cycles, Views, Find and filter.

The pattern is familiar. The part worth stealing is the editorial discipline behind it. Each card has a one-line description that starts with a verb: "Learn how to import issues from other tools," "Configure workflows for your team." There's no marketing copy bleeding into the card grid, no "Unlock the power of Linear" filler. Every card is a promise of a task you can complete on the linked page.

Most product docs hubs I've audited (I run Docsio, which generates docs sites from AI, so I see a lot of them) default to a long sidebar and a homepage that's either empty or a landing-page-shaped thing with feature marketing smuggled in. Linear does the opposite. The homepage is the navigation, rendered as a browseable grid, and the sidebar exists as a secondary affordance for people who already know where they're going.

The sidebar is organized by concept, not by feature list

Click into any article and the left sidebar stays pinned. The top-level groupings read like Linear's internal mental model: Getting started, Account, Your sidebar, Teams, Issues, Issue properties, Projects, Initiatives, Cycles, Views, Find and filter, AI, Linear Asks, Integrations, Analytics, Administration.

That ordering is not alphabetical. It's not by feature shipping date. It's roughly the order in which a new user encounters concepts as they onboard. Account settings come before Teams because you pick your notifications before you join anything. Teams before Issues because you need a team to file issues in. Issues before Issue properties because the noun comes before the adjective.

It sounds obvious when you describe it, but most docs sidebars I see are organized by whatever the engineering team's feature tree looks like, or alphabetically with a "Getting Started" bolted on top. Linear's sidebar is a taxonomy of the product's concepts in the order you hit them. Stealable immediately, and it costs nothing beyond deciding once. See our notes on organizing documentation for the version of this applied outside Linear.

Keyboard shortcuts rendered as real chips, everywhere

This is the small thing I liked most. On the /docs/projects page, when the text says you can add an issue to a project by pressing Shift then P, the shortcut is rendered as two pill-shaped chips side by side, styled the way Linear's actual in-app command bar renders them. Same for Cmd + I to toggle the sidebar, C to create, and so on.

A lot of docs write keyboard shortcuts as inline code with backticks, so you get Shift+P sitting in a run of prose. It's fine. It's not wrong. But Linear's pill-chip treatment does two things at once. It makes the shortcut visually parse out of the paragraph so your eye lands on it when scanning, and it reinforces the in-app visual language so that when you see the chip in the docs and later see it in the command bar, you recognize it as the same object.

This is the sort of thing that reads as polish in isolation but compounds when it's done consistently. Every page that mentions a shortcut uses the chip. Over a hundred pages, the UI becomes legible.

The docs link out to the Linear Method, and it's a real site

Linear maintains The Linear Method as a separate property: not product docs, but a philosophical guide to how they think software should be built. Principles, direction, execution, building in public. It reads as opinionated essay content, not marketing.

The docs link out to the Method in a few well-chosen places. In the Projects FAQ there's a "How we work" block that pulls in a first-person quote about how Linear's own team uses Projects. It doesn't say "learn more in our blog." It says, here's how we actually run this, and here's the longer thinking behind it.

Most SaaS companies try to do this with a blog and it turns into a content marketing funnel. Linear treats the Method as a peer to the docs, with its own information architecture, its own writing voice, and enough internal gravity to stand on its own. The docs get to stay practical. The Method gets to be opinionated. And the cross-links give each property a reason to exist.

This one isn't free to copy. You need something genuinely worth saying before you can spin up a second site. But the pattern (split the practical how-to from the why-we-think-this-is-right) is worth naming. I've seen the inverse many times: docs pages bloated with philosophical preambles because the company wanted the opinion captured somewhere.

The dev docs are a separate site, and that's the right call

Linear splits developer docs onto linear.app/developers: GraphQL API, authentication, agents, TypeScript SDK, guides. The product docs at linear.app/docs don't try to cover any of that surface.

This is the opposite of what most B2B SaaS tools do when they outgrow a single site. The usual move is to cram an "API" section into the bottom of the main sidebar and call it done. Linear recognized that API consumers and end users are different audiences, behave differently, and scan docs with different mental models, so they're different sites with different navigation.

What's interesting is that the developers site is also the place where Linear's "Agent Interaction Guidelines" live: a short framework for how AI agents should read and write into Linear via the API. That's a first-mover move you'd expect from a company with opinions, which Linear has. For context on when to split vs. merge docs, see our api documentation examples roundup.

What I think they got wrong: no visible table of contents on long pages

The Projects page runs about 2,000 words and covers create, delete, view, adding issues, custom views, project details, multi-team projects, timeframes, and a six-question FAQ. It's a lot. And there's no right-side table of contents or anchor nav to help you jump to the part you actually came for.

If I land on /docs/projects because I searched "how do I add issues to a Linear project," I have to scroll past the overview, past the create/delete sections, past the view toggles, before hitting the "Adding issues" heading. A right rail with H2 anchors (the pattern Stripe, Vercel, Mintlify, and most modern docs sites use) would save the round trip.

The defense of Linear's choice is probably that the search is fast enough that you should just search for "adding issues" instead of reading the whole page. And the search is genuinely fast. But the gap between search-landed and TOC-assisted is where scannability lives, and for longer pages Linear is leaving usability on the floor. Our notes on docs site search bars get into the tradeoff.

The other thing I'd change: more screenshots, captioned better

The Projects page has two embedded screenshots. The Start guide page I checked has zero. For a product whose core value proposition is "the UI feels good," the docs underweight the UI.

Compare against Notion or Arc, whose docs are closer to 50% visual by screen area, and you notice that Linear's text-forward approach is an active choice, not an oversight. I get why they do it (screenshots age fast, the UI ships weekly, someone has to re-screenshot constantly) but the tradeoff leans too far toward prose. A product team whose docs describe workflows in paragraphs is relying on the reader to reconstruct the UI from text, and the reader's reconstruction is often wrong.

An automated screenshot-regen pipeline would fix the maintenance problem, but I suspect Linear just accepts the staleness cost and prefers not to ship screenshots at all. It's a defensible call. I still think they're missing the cheapest wins.

What I'd steal

The editorial shape of the hub page: card grid with verb-led one-line descriptions, no marketing copy in the grid. The sidebar ordered by the user's mental model, not by feature tree. Pill-chip rendering of keyboard shortcuts that matches the in-app treatment. The split between product docs and developer docs as two separate properties with separate navigation. A peer philosophical site (the Method) that keeps the main docs practical.

What I'd avoid

Skipping a right-rail table of contents on pages over 1,500 words. Treating screenshots as optional for a UI-first product. Assuming fast search compensates for thin on-page navigation, it doesn't, and the bounce rate on mobile will tell you so.

If you're building product docs for a SaaS tool in 2026, Linear's information architecture is a better reference than Notion's or Intercom's: it's disciplined, it respects the reader's time, and the aesthetic restraint reads as confidence rather than minimalism-by-default. Just add the TOC they forgot.