Docs need a real home and edits people can trust
@karrisaarinen asked what would make Linear the place for team, agent and markdown docs. This reads all 137 replies from 104 people for what they asked for, the needs underneath, and where to start.
- People asked for folders, a Documents sidebar, personal docs, external sharing, version history, suggestion mode, git sync, and embeds.
- Underneath, teams need docs that live independently of projects, that agents and people can edit without losing work, and that stay true after shipping.
- Linear should treat docs as the written half of the work, owned by a person, living where they are created, and kept in sync by agents through reviewable diffs.
Starting a new project at @linear let us know what do you need for making linear the place for your team/agent/markdown etc documents

What they need
Docs need a home before projects exist31 people
PMs and engineers need one place to create and find docs that are not yet, or no longer, tied to a project or team.
- Asks it explains
- folders, sidebar entry, personal docs, nested docs, search, standalone docs
- If we do nothing
- Drafts and lasting product knowledge stay in Notion and Google Docs, and Linear docs remain project attachments nobody can find.
- Themes
- Doc organization and findability, Docs outside teams/projects, Templates
- Said best by
@dradriannestone@JulianLaneve@isaiahdahl3 repliesShow repliesHide
Agents and people editing safely together30 people
Teams need agents, scripts, and people to change the same doc without clobbering each other, losing comments, or hiding what changed.
- Asks it explains
- revision IDs, patch API, suggestion mode, version history, git protocol, read-only lock
- If we do nothing
- Teams will not let agents touch canonical docs, so Linear loses its strongest advantage over Notion.
- Themes
- Agent and API editing, Version history and suggested edits, Git-backed docs, Permissions inside workspace
- Said best by
@johnroodepic@podviaznikov@LLiepenieks3 repliesShow repliesHide
Docs that stay true after shipping23 people
Teams need product docs to reflect the product as it is today, because nobody has time to audit stale pages by hand.
- Asks it explains
- staleness flags, two-way links, decision log, half-life decay
- If we do nothing
- Linear docs rot into the same junk drawer that @paulozoom says his Notion already is.
- Themes
- Staleness and freshness, Linking docs to work
- Said best by
@paulozoom@ItsPatrickU@_stevenchen3 repliesShow repliesHide
Coworkers without seats can review11 people
Product teams need seatless coworkers and some clients to read and comment on briefs, or the review loop moves back to Google Docs.
- Asks it explains
- share by link, viewer seats, guest access, external sharing
- If we do nothing
- Teams keep paying for Notion or Google Docs purely to share briefs, as @sambhall and @mccun934 describe.
- Themes
- Sharing with non-Linear users
- Said best by
@nkrekow@joesaunderson@mccun9343 repliesShow repliesHide
Recommendation
A Linear doc should be the written half of the work, starting as a spec, recording decisions, and becoming product knowledge after shipping. Docs live where they are created, have an owner, and change through reviewable diffs that let agents keep them in sync.
First slice
- Docs live where they are created, and docs with no context sit in a Documents sidebar, author-owned and workspace-visible, until linked to work.
- We should ship a revision-checked patch API and MCP tool with lossless markdown round-trips and comments that stay anchored.
- Agent and API edits to published docs should appear as a diff that the doc owner accepts or rejects.
Then
- Linear should flag a doc as possibly stale when linked issues or projects ship or change.
- The Linear Agent should then draft the update as a proposed diff for the owner.
- We should add free company-email viewer and commenter access covering docs and project briefs.
- We should support sandboxed HTML artifacts and images with markdown fallbacks that agents can read.
Not building
- Folders and custom taxonomiesFolders fix where a doc lives but not whether it is true, and they rebuild the Notion junk drawer.
- Native git protocolGit is a transport choice, and @podviaznikov's real pain is lossy edits and drifting comments, which a patch API fixes.
- Google Docs permission matrixMost askers mean seatless coworkers, so per-email roles add configuration for a problem that is mostly about seat cost.
- Embed anything and whiteboardsAn iframe board is opaque to agents and pushes docs toward a block editor that weakens plain markdown.
- Personal docs by defaultPersonal-by-default works against findability, the biggest theme, and recreates the stale drawer once per person, so private stays an opt-in escape hatch.
Validate first
- Do teams accept diff review on every agent edit, or only on docs marked as published?
- Is single-parent nesting enough structure once a workspace has hundreds of docs?
- How often does external sharing mean clients rather than seatless coworkers, and does that change the access model?
- Can linked-work signals flag staleness accurately without burying owners in false alarms?
What they asked for
Replies that ask for several things count toward each theme. Open one for its framing and replies.
Doc organization and findabilityFolders, nested or sub-docs, a top-level Documents section, and good search so docs are easy to find.23 people
Folders, nested or sub-docs, a top-level Documents section, and good search so docs are easy to find.
- Underlying need
- Teams need a single trustworthy place to find any document, including ones that exist before a project does, and to know whether it is still current.
- Why it misleads
- Folders fix where a doc lives, but @paulozoom and @_stevenchen say the bigger pain is not knowing which docs are still true.
- Docs hang off projects and teams today, yet @dradriannestone notes that docs often come before the project they would belong to.
- Configurable folder trees recreate the Notion junk drawer that @paulozoom says his team is already drowning in.
- Direction
- We should make Documents a first-class workspace sidebar section with fast search, parent and child nesting as the only structure, and freshness signals driven by linked issues and agents. We are killing labels, custom taxonomies, and deep folder systems.
- Open questions
- Would a workspace-level Documents page with nesting and search satisfy teams that explicitly asked for folders?
- Which signals reliably show that a doc is stale: linked issue changes, age, or an agent comparing the doc against shipped work?
- Should a doc be able to live unattached at the workspace level and later be linked to a project without being moved?
Agent and API editingAgents and the API/MCP should read and edit docs reliably: targeted patches, clean markdown round-trips, comments that stay in place, and no clobbered edits.22 people
Agents and the API/MCP should read and edit docs reliably: targeted patches, clean markdown round-trips, comments that stay in place, and no clobbered edits.
- Underlying need
- Teams need agents and scripts to change shared docs without humans losing work, losing comment context, or losing track of what changed and why.
- Why it misleads
- Git protocol support, which @podviaznikov and @aidansunbury asked for, is a transport choice, and building it would not fix the lossy markdown and comment drift underneath.
- Patch APIs alone make edits smaller, but they still let unreviewed agent changes land silently in docs people rely on.
- Karri mostly writes through the in-app agent, so the team may underrate how broken the API and MCP round-trip feels to external agents.
- Direction
- We should make agent and API edits arrive as revision-checked patches that show up as reviewable diffs in the doc, with lossless markdown and anchored comments. We should drop git hosting and bidirectional file sync as the primary bet.
- Open questions
- Should agent edits default to proposals that need human approval, or apply directly with an easy revert?
- How lossy is the current markdown round-trip today, and which constructs like tables, nested lists, and comments break most often?
- Do teams want docs synced to their repos, or do they only want history and diffs that their agents can read?
Linking docs to workTwo-way links between docs and issues, PRs and projects, including capturing decisions from Slack, PRs or tickets into docs.17 people
Two-way links between docs and issues, PRs and projects, including capturing decisions from Slack, PRs or tickets into docs.
- Underlying need
- Teams need the knowledge behind their work (specs, decisions, how things work today) to stay connected to the issues and projects it describes, and to stay true after shipping.
- Why it misleads
- Two-way links alone solve where a doc lives, not whether it is still accurate, which @ItsPatrickU and @sanketpath flag as the real pain.
- Project-bound docs die when the project ships, so linking them harder to projects deepens the staleness problem rather than fixing it.
- Requests like ontologies and relation vocabularies from @eulerfx point toward a configurable knowledge graph that most teams will never maintain.
- Direction
- We should make docs first-class objects that reference issues and projects both ways, outliving any single project. Linear's agent should capture decisions from Slack and PRs into them and flag a doc as stale when the linked work moves.
- Open questions
- Do teams actually want the agent to edit docs when linked work changes, or only to flag drift for a human?
- Is the spec-before-work doc a separate object, or should it simply be the issue or project description that agents read?
- How many teams already keep decision logs in Notion or Obsidian, and would linking to them be enough instead of moving them?
Docs outside teams/projectsPersonal or workspace-level docs that aren't tied to a team, project or issue.14 people
Personal or workspace-level docs that aren't tied to a team, project or issue.
- Underlying need
- People need a home for documents that exist before, between, or after projects, so drafts, cross-cutting knowledge, and living product docs do not get forced into the wrong container.
- Why it misleads
- Folders and personal workspaces fix where a doc lives, but @paulozoom and @ItsPatrickU say the bigger pain is docs going stale.
- A full org, team, and personal hierarchy like @PeterSkott describes would rebuild Notion inside Linear and dilute the issue-tracking core.
- Personal docs really mean deferring placement, not privacy: @judahguttmann says not everything starts as a project, and @JulianLaneve does not care who sees his docs.
- Direction
- We should treat a Linear doc as the written half of the work, living where it is created. Docs with no context should be author-owned, workspace-visible and unfiled until linked or agent-placed, never personal by default, built on revision-checked API, MCP and agent diffs.
- Open questions
- Will unfiled, author-owned workspace docs stay findable, or does the Linear Agent need to suggest a home for each one quickly?
- Can project links and agent-driven review solve staleness, for example by flagging docs whose linked work has changed?
- If Linear does nothing, does losing personal drafts and living docs to Notion weaken Linear's role as the context source for agents?
Sharing with non-Linear usersShare docs by link or email with people who don't have Linear seats, such as clients or other departments, with view or comment access.11 people
Share docs by link or email with people who don't have Linear seats, such as clients or other departments, with view or comment access.
- Underlying need
- Teams need the people who review and consume product work but will never hold a Linear seat to read and comment on docs without that work moving to Google Docs or Notion.
- Why it misleads
- Copying the full Google Docs permission model would turn a narrow review need into a sprawling access-control system.
- Most askers mean coworkers without seats, not the public internet, so @nkrekow and @mccun934 describe a seat-cost problem more than a publishing problem.
- Treating this as a docs-only feature ignores @joesaunderson, who wants the same read access to project briefs and issues.
- Direction
- We should add free workspace viewer and commenter access for anyone with a company email, covering docs and project briefs. The one escape hatch should be a revocable public link that also serves raw markdown at a stable URL. We should not build per-email external sharing with granular roles.
- Open questions
- Would company-only viewer access be enough to retire the Notion or Google Docs instance, or do clients and agencies like @abdul_quadir_a and @aesadde make external links a must?
- Does free commenting by non-seat users cannibalize paid seats, and where should the line between commenting and editing sit?
- Should the shareable unit be a document, or any project brief and issue view, as @joesaunderson suggests?
Version history and suggested editsVersion history, diffs and suggestion mode so human or agent edits can be reviewed before they're accepted.10 people
Version history, diffs and suggestion mode so human or agent edits can be reviewed before they're accepted.
- Underlying need
- Teams need to trust document changes, especially agent edits, by seeing what changed, who changed it, and approving it before it becomes the accepted version.
- Why it misleads
- Version history alone is a passive log, and nobody reads logs after an agent quietly rewrites a spec.
- Git-backed docs, as @podviaznikov and @aidansunbury suggest, serve engineers but exclude the PMs and designers who write most docs.
- Suggestion mode copied from Google Docs treats agents like slow human typists, when agents produce whole-document revisions that need diff-level review.
- Direction
- We should make agent edits to docs land as proposed changes that a human reviews as a diff, reusing Linear's existing review patterns, with plain version history underneath. Git protocol access can come later as an escape hatch for engineers, not as the core model.
- Open questions
- Should human edits default to direct writes while agent edits default to proposals, or should each team choose?
- Is the bigger pain reviewing agent edits or keeping docs current, as @_stevenchen describes, which would mean agents must also proactively propose updates?
- How often do teams actually lose work to concurrent overwrites, as @jackonawalk reports, and is that a separate editor bug?
Staleness and freshnessFlag or prevent stale docs and keep docs current with the product as it evolves.9 people
Flag or prevent stale docs and keep docs current with the product as it evolves.
- Underlying need
- Teams cannot trust whether a doc still describes the product as it is today, and nobody has time to audit them, so docs rot into a junk drawer.
- Why it misleads
- A time-based staleness badge or half-life decay flags old docs that are still true and misses new docs that are already wrong.
- A flag only tells people a doc is stale, and @paulozoom says nobody has time to fix stale docs anyway.
- The revision ID ask from @johnroodepic is about agent write conflicts, not freshness, and it should be handled as a separate API concern.
- Direction
- Freshness should come from linked work, not from the calendar. When an issue, PR, or project linked to a doc ships or changes, Linear should mark the doc as possibly out of date and have the Linear Agent draft an update for the doc owner to approve.
- Open questions
- Do teams link docs to issues and PRs reliably enough for change-driven staleness to work, or does the agent need to infer those links?
- Should living product docs, the ones @ItsPatrickU describes, be a distinct doc type from project decision logs, with only the living type tracked for freshness?
- Will doc owners actually review agent-drafted updates, or do the updates need to ship as auto-applied edits with an undo?
Rich media and embedsEmbed images, video, HTML prototypes, whiteboards like Whimsical or tldraw, and other non-markdown files in docs.9 people
Embed images, video, HTML prototypes, whiteboards like Whimsical or tldraw, and other non-markdown files in docs.
- Underlying need
- Teams increasingly explain product shape through visual artifacts like prototypes, diagrams and mockups, often agent-generated, and prose-only docs force those artifacts to live somewhere else.
- Why it misleads
- Building "embed anything" pushes docs toward a Notion-style block editor and erodes the plain markdown that agents and the API rely on.
- An iframe of a Whimsical or tldraw board shows the content to people, but agents cannot read it, so the context stays outside Linear.
- Branded PDF output from @sea_viva and image annotation from @wiretransfer are separate needs, and bundling them in would bloat the scope.
- Direction
- We should make sandboxed HTML artifacts and images first-class in docs, and give every embed a markdown text fallback that agents can read. We should not build a native whiteboard, a generic file store, or branded export.
- Open questions
- Are most of these visual artifacts agent-generated HTML, or are they hand-made boards in Whimsical and tldraw?
- Do agents need to edit embedded artifacts, or is reading a text summary of them enough?
- How often does the visual need to render inline, and how often would a rich link preview cover the job?
Permissions inside workspaceView vs edit permissions, read-only or locked docs, private docs, and doc ownership or approval.5 people
View vs edit permissions, read-only or locked docs, private docs, and doc ownership or approval.
- Underlying need
- Four people want canonical docs like policies to stay trustworthy and drafts to stay private until ready, so Linear can hold real team knowledge without accidental edits.
- Why it misleads
- A per-doc view and edit permission matrix adds configuration that Linear's open-by-default workspace has deliberately avoided.
- Most replies describe fear of accidental edits (@paulozoom, @Roywulms), which ownership and history solve better than access control.
- Locks that only stop people will fail, because the Linear Agent, API and MCP server also edit docs.
- Direction
- We should give every doc an owner who keeps it true and approves edits, with people's and agents' changes arriving as revision-checked diffs; private is an escape hatch, not the default. We are killing per-doc role matrices, folder permissions and personal-by-default docs.
- Open questions
- Are accidental edits to policy docs actually happening, or is the lock request mostly about reassurance?
- Do teams need the draft history wiped on publish, as @paulozoom asked, or is hiding it from viewers enough?
- Should agents edit published docs only through owner-approved proposals, or are direct agent edits acceptable with clear attribution?
TemplatesDoc templates with placeholder text that shows what to fill in.4 people
Doc templates with placeholder text that shows what to fill in.
Git-backed docsDocs backed by git: clone and push docs, edit them through PRs, or view a repo's .md files in Linear.3 people
Docs backed by git: clone and push docs, edit them through PRs, or view a repo's .md files in Linear.
- Underlying need
- Teams want Linear docs to behave like code artifacts that agents and engineers can diff, version, review, and sync without lossy round trips or new tooling.
- Why it misleads
- Running a git protocol layer is a large infrastructure bet, and @podviaznikov's real complaint is that API edits rewrite untouched paragraphs and reset comments.
- PR-based review, as @aidansunbury asked for, may really be a request for change review and history inside Linear rather than for GitHub specifically.
- The repo .md viewer from @isaiahdahl is mostly a symptom of his organization complaint, and it would create a second, read-only doc system.
- Direction
- We should first make the API and MCP edit model lossless, with block-level diffs, stable comment anchors, and visible version history. After that, we can add one-way repo sync of .md files as the single escape hatch, and we should kill native git protocol for now.
- Open questions
- Do the lossy API diffs that @podviaznikov describes come from how we convert markdown, and how many agent-driven teams hit this problem?
- Would in-Linear suggested changes with a review step satisfy people who asked for PRs, or do they specifically need GitHub's review tooling?
- Is the main use case keeping repo docs such as specs and ADRs visible in Linear, or authoring in Linear and publishing out to the repo?
One-offsAsks no one else made19 people
Asks no one else made
Praise and asidesExcitement, jokes, and questions about the project32 replies
Excitement, jokes, and questions about the project
Deeper dives
The decisions under the recommendation, with the options side by side.
Where a new doc livesPersonal, team, workspace, or something else?
Personal, team, workspace, or something else?
"Personal", "team" and "workspace" each bundle three separate choices: who owns the doc (keeps it true), who can see it, and where it lives. The asks only conflict when the three are tied together.
| Default | Owner | Seen by | Lives in | Cost |
|---|---|---|---|---|
| Personal | You | You | Your space | Hidden by default, so it can't be found, and every person grows their own stale drawer |
| Team (today) | The team | Workspace | A team | You pick a team before you know one; some docs belong to none |
| Workspace | Nobody | Workspace | Workspace | Visible but unowned, which is how wikis rot |
| Unfiled, owned | You | Workspace | Nowhere yet | Needs a nudge so unfiled stays short |
Karri's answer today is the team row: "create the documents under some team and then move to a new place when needed" (@karrisaarinen). It works, but it makes you file before you know. @JulianLaneve says "where to put it" becomes awkward, @paulozoom wants docs "not in any one team", and @judahguttmann says "Not everything is a project from day one."
The personal ask is about when to file, not privacy. Julian's workflow: share it by link ("I don't care if other people can see it"), then "eventually move it to a team" (@JulianLaneve).
Recommendation: home comes from where you create it; with no context, the doc is yours, visible to everyone, and unfiled until it earns a home. Private is something you choose.
Watch: "unfiled" becomes its own junk drawer if nothing pulls docs out. The owner is who the agent nudges.
How agents and people edit the same docWhat keeps an agent's write from undoing a person's?
What keeps an agent's write from undoing a person's?
People here edit docs through the app, the Linear Agent, the API, MCP, and local files synced by their own agents. The pain is all at the seams: @podviaznikov says API updates reset comment positions and rewrite untouched paragraphs, and @jackonawalk has seen "people overwrite others' changes."
| Approach | Keeps your edits | Reviewable | Friction | Asked for by |
|---|---|---|---|---|
| Overwrite (the API today) | No | No | None | Nobody |
| Edit locks | Yes | No | High | @paulozoom |
| Revision-checked patches | Yes | Partly | Low | @johnroodepic, @pacificdaemon |
| Agent edits as proposals | Yes | Yes | One click | @LLiepenieks, @_stevenchen, @jeffwjeffw |
| Git and PRs | Yes | Yes | High for non-engineers | @aidansunbury, @podviaznikov |
The revision check, in John's words: "If I edit a paragraph while an agent is working, its stale write should fail, not quietly undo mine." In practice:
- The agent reads the doc at revision 12.
- You edit a paragraph, so the doc is now at revision 13.
- The agent writes "only if still at 12" and is turned away.
- It re-reads and retries, or files its change as a proposal for you.
Karri doesn't hit these issues because he writes "mostly with the linear agent, vs through the api or mcp" (@karrisaarinen). The first-party path is smooth; third-party agents are where it breaks, and that's where more and more edits come from.
Recommendation: every write is revision-checked and touches only the blocks it changes (table stakes, no UI). On docs with an owner, agent edits arrive as proposals by default. Locks and git aren't needed once both exist: @f already argues revisions make locks "just adding friction", and Karri's reply to git was "everyone check out the git repo?" (@karrisaarinen).
How a doc stays trueWhat tells you a doc is out of date?
What tells you a doc is out of date?
@paulozoom calls it "the million dollar need": "most of our notion is out of date and nobody's got the time to figure out what's still relevant." @ItsPatrickU says Linear docs "go stale once they ship."
| Signal | Effort | False alarms | What it catches |
|---|---|---|---|
| Age, a half-life (@PeterSkott) | None | Many | Old docs, including stable ones that are still right |
| Owner review (@timfl93) | A chore | Few | Whatever the owner remembers to check |
| Linked work changed | None | Some | Docs whose subject shipped or moved |
| Agent proposes the fix (@_stevenchen) | One review | Some | The same docs, with the update already drafted |
Only Linear knows when the work a doc describes has shipped or changed, so that's the signal no Notion or Google Doc can copy. It also gives a doc a life that follows the work: a spec before it, decisions during it, product knowledge after it ships. Through all three, the doc stays linked to its issues, projects and PRs, and when one of them moves:
- Linear flags the doc as possibly out of date.
- The Linear Agent drafts the update as a diff.
- The owner accepts or rejects it.
@camdesignstuff wants the start of this: "the one-pager on what done looks like, written before the work. If agents read it each time they pick up the issue, that page becomes the spec."
Recommendation: freshness comes from linked work, never from age, and every flag arrives with a proposed fix so it's a review, not a chore. Depends on: docs being linked to work, which the default home (above) makes the normal case.
Who can read without a seatHow much sharing does this actually need?
How much sharing does this actually need?
Sharing is the one thing several teams say keeps Notion or Google Docs around: @sambhall ("the one use case we keep notion around for"), @mccun934 ("license restrictions for sharing documents were a blocker"). Karri asked the right question: "like anyone on the internet or just internally inside the company but who are not linear users" (@karrisaarinen).
| Option | Colleagues | Clients | Admin | Seat risk |
|---|---|---|---|---|
| Per-email roles (@isaiahdahl) | Yes | Yes | High | Low |
| Free company viewers (@joesaunderson) | Yes | No | None | Some |
| Public link (@aesadde) | Yes | Yes | None | Low |
| Client guests (@abdul_quadir_a) | No | Yes | Some | Low |
The answer to Karri came back quickly: "internally would satisfy our needs for anyone at the company who isn't a linear user" (@nkrekow). Joe wants the same for project briefs, "Almost like the Vercel viewer seats."
| Who | Read | Comment | Edit |
|---|---|---|---|
| Anyone with a company email | Free | Free | Needs a seat |
| Anyone with the public link | Yes | No | No |
Recommendation: anyone with a company email can read and comment for free, on docs and project briefs alike; one public link per doc covers clients (and serves raw markdown at a stable URL for agents, as @KeithZhai asked). No per-email roles. Open: free commenters are a pricing decision, not a product one.
137 replies and quotes from outside Linear, fetched Oct 5, 6:49 PM ET. Claude named the themes, TypeSafe's Jev sorted each reply into them, and Claude framed the needs with Karri's Linear Way prompt.
