Linear on X
DocumentsTeam Paused for now

Documents in Linear

Linear documents · Oct 5

Docs need a real home and edits people can trust

Context

@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.

TL;DR
  1. People asked for folders, a Documents sidebar, personal docs, external sharing, version history, suggestion mode, git sync, and embeds.
  2. Underneath, teams need docs that live independently of projects, that agents and people can edit without losing work, and that stay true after shipping.
  3. 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.
Karri Saarinen@karrisaarinenOct 5, 10:57 AM

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

  1. 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
    • Please make it a top level navigation item. Having to dig around to find the documents that were attached to a project or issue was annoying. As a p.m. the documents also often preceded the issue so having to tie it to a project or issue that didn’t exist yet was annoying.

    • Julian LaNeve@JulianLaneve· replying to @karrisaarinen

      personal documents would solve a lot of what I need, my workflow would prob be: - upload a personal doc - share that via link (I don’t care if other people can see it / don’t really need sharing perms) - eventually move it to a team if it belongs there

    • Isaiah Dahl@isaiahdahl

      Primary friction I have is around how documents can be organized. - Make documents a more first party entity (not just a resource type) I want to see "Documents" in the sidebar - Teams have a "Documents" tab, Projects have Resources that are just a list of links, one could be a external link, one could be a document, but then Team Home organizes documents by project? - Documents page in Team feels like an issues list. Something about that mental model doesn't feel like the right home for all my documents. - Connect a repo and view all the .md files organized like they are in code. Maybe read only?

  2. 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
    • John Rood@johnroodepic

      Give every doc read a revision ID and let API writes require that revision. If I edit a paragraph while an agent is working, its stale write should fail, not quietly undo mine.

    • it should be possible to integrate linear docs via api and cli with github actions and things and it should properly support bidirectional sync - which is doesn’t now. it shouldn’t change paragraphs that were not touched. so diff should be clean and show only what relay changes by user

    • Linards Liepenieks@LLiepenieks

      agent edits as reviewable diffs on docs, like code

  3. 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
    • Paulo@paulozoom

      couple more - workspace level docs, not in any one team - the million dollar need: solve the junk/stale drawer problem that inevitably happens with team docs. most of our notion is out of date and nobody’s got the time to figure out what’s still relevant and not, it’s a mess.

    • PatrickUllrich@ItsPatrickU

      Linear docs are a great decision/delta log, but they're tied to projects and go stale once they ship. What I want is internal docs for the product as it is today, like "how to set up a client on this integration," linked back to the projects that built it. Team docs could theoretically be a place but that’s assuming a lot about the org structure.

    • Steven Chen@_stevenchen

      overall, keeping docs current takes a tremendous amount of manual effort; we need a way for agents to propose updates that humans can review.

  4. 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
    • nick krekow@nkrekow· replying to @karrisaarinen1 like

      internally would satisfy our needs for anyone at the company who isn’t a linear user…while would love for everyone to use linear just not gonna happen at least at this point in time and can’t justify getting paid seats just to view product briefs when gdocs exists for free

    • Joe Saunderson@joesaunderson· replying to @karrisaarinen

      I would like this for project/issues too... I often have internal users asking for a project brief... but I don't want to pay for a seat for them to have a glance. Almost like the Vercel viewer seats

    • Mike McCune@mccun934· replying to @nkrekow

      agree with this. trying to get away from Notion but the license restrictions for sharing documents were a blocker for us

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

  1. 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.
  2. We should ship a revision-checked patch API and MCP tool with lossless markdown round-trips and comments that stay anchored.
  3. Agent and API edits to published docs should appear as a diff that the doc owner accepts or rejects.

Then

  1. Linear should flag a doc as possibly stale when linked issues or projects ship or change.
  2. The Linear Agent should then draft the update as a proposed diff for the owner.
  3. We should add free company-email viewer and commenter access covering docs and project briefs.
  4. We should support sandboxed HTML artifacts and images with markdown fallbacks that agents can read.

Not building

  1. Folders and custom taxonomiesFolders fix where a doc lives but not whether it is true, and they rebuild the Notion junk drawer.
  2. Native git protocolGit is a transport choice, and @podviaznikov's real pain is lossy edits and drifting comments, which a patch API fixes.
  3. Google Docs permission matrixMost askers mean seatless coworkers, so per-email roles add configuration for a problem that is mostly about seat cost.
  4. Embed anything and whiteboardsAn iframe board is opaque to agents and pushes docs toward a block editor that weakens plain markdown.
  5. 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

  1. Do teams accept diff review on every agent edit, or only on docs marked as published?
  2. Is single-parent nesting enough structure once a workspace has hundreds of docs?
  3. How often does external sharing mean clients rather than seatless coworkers, and does that change the access model?
  4. 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
  1. Folders fix where a doc lives, but @paulozoom and @_stevenchen say the bigger pain is not knowing which docs are still true.
  2. Docs hang off projects and teams today, yet @dradriannestone notes that docs often come before the project they would belong to.
  3. 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
  1. Would a workspace-level Documents page with nesting and search satisfy teams that explicitly asked for folders?
  2. Which signals reliably show that a doc is stale: linked issue changes, age, or an agent comparing the doc against shipped work?
  3. Should a doc be able to live unattached at the workspace level and later be linked to a project without being moved?
24 replies
  • Alano@Alano522

    Proper nested folder hierarchies and fast fuzzy search across docs, so things do not get buried once a workspace gets large.

  • Joshua Guinness@joshua_guinness1 like

    Folders or sub documents for us! Just a way for us to more easily organise and group them

  • Isaiah Dahl@isaiahdahl

    Primary friction I have is around how documents can be organized. - Make documents a more first party entity (not just a resource type) I want to see "Documents" in the sidebar - Teams have a "Documents" tab, Projects have Resources that are just a list of links, one could be a external link, one could be a document, but then Team Home organizes documents by project? - Documents page in Team feels like an issues list. Something about that mental model doesn't feel like the right home for all my documents. - Connect a repo and view all the .md files organized like they are in code. Maybe read only?

    Also counted in Git-backed docs
  • Please make it a top level navigation item. Having to dig around to find the documents that were attached to a project or issue was annoying. As a p.m. the documents also often preceded the issue so having to tie it to a project or issue that didn’t exist yet was annoying.

  • Robert van Hoesel@robertvhoesel· replying to @karrisaarinen

    nice! We'll also need some form of document structuring, either nesting or folders, beyond that they're my favorite place to write.

  • Paulo@paulozoom3 likes

    - some organization: folders, sections, or nested docs - private docs shared only b/w a few people. some docs start private, then open up later to all (history wipe pls) - lock for edits, just to avoid accidental edits

    Also counted in Permissions inside workspace
  • - organize docs way way better. the doc organization is such a painpoint I'd say just ship somethin like gdocs then fast-follow on polish. - sticky headers in tables - doc attachments on projects are hard to navigate

  • being able to share docs with those outside of linear - not necessarily for editing but at least viewing ideally commenting - it’s one of the big reasons we use gdocs over linear docs so teams who don’t use linear can review (anyone outside of product/design/eng) the other request being better organization they are too hard to find today

    Also counted in Sharing with non-Linear users
  • - Document permissions (view vs edit) - Organize documents (with labels? Folders?) At the moment, we organize our policies in Linear. It actually works very well, if you find a good structure. But the docs are hard to find and everyone can edit them.

    Also counted in Permissions inside workspace
  • Steven Chen@_stevenchen

    - project docs are a flat list of links with no clear signal for what’s current or important - human-readable decisions get mixed with agent-generated specs - decisions made in PRs, tickets, & comments are hard to find later as a coherent explanation of why we built something

    Also counted in Staleness and freshness
  • Should be org->team->personal markdown knowledge in a folder structure in that order each level you should be able to define a set of categories you want to sort context into, with a jev type model. There should be a context half-life decay for all docs that provides a lifecycle

    Also counted in Staleness and freshness, Docs outside teams/projects
  • Tim@timfl93

    - Workspace level Documents page (all documents you can access) with ways to create pages to structurally surface them (wiki) - Document ownership flow (e.g. set responsibility for content, edit / approval?) - Personal documents I can share with others not tied to teams

    Also counted in Docs outside teams/projects, Permissions inside workspace
  • Ben Adelson@BenAdelson

    Documents for projects, ideas, marketing docs/skills, decision trees Related to customers like case studies by customer, maybe more for CS teams to manage communications Easier way to view documents by issue or project.

    Also counted in Linking docs to work
  • Sandi@L47HAHA

    Having a good way to do weekly’s. Maybe templates like you can have for bugs. Having the ability to have have folders

    Also counted in Templates
  • DJ Brinkerhoff@djbrinkerhoff

    making them read only linking docs together/having parent child relationships

    Also counted in Permissions inside workspace
  • oorestisime@oorestisime

    Personal workspaces, templates, indexing searching (big pain) and connecting nodes, connected issues/prs.

    Also counted in Linking docs to work, Templates, Docs outside teams/projects
  • Paulo@paulozoom

    couple more - workspace level docs, not in any one team - the million dollar need: solve the junk/stale drawer problem that inevitably happens with team docs. most of our notion is out of date and nobody’s got the time to figure out what’s still relevant and not, it’s a mess.

    Also counted in Staleness and freshness, Docs outside teams/projects
  • Amazing! - Home for documents to create/find them easily - Carousals for attachments - Annotate images cos this in itself is a great - documentation for agents - One-click link related issues/PRs - surface if issues/prs moved ahead but doc is stale - Copy as markdown with link included

    Also counted in Linking docs to work, Staleness and freshness, Rich media and embeds
  • Saad Salman@thesaadsalman

    Making a Document within a Project is fine, but sometimes I make a document independently and then attaching it to the Project is a hassle. And trying to look for Documents not in a project, other than using Search, also difficult - I have to go to the Org page?

    Also counted in Docs outside teams/projects
  • lEvIDel@l3ViDel· replying to @joshua_guinness

    link

  • working using api should work. updating document using api should not reset position of the comments. so ui flow should match api. and it should be usable for people and agents. ui placement for document is really bad. not possible to find them in menu.

    Also counted in Agent and API editing
  • nested docs - today they can only be in a Project or Team. We want to build out a Knowledge base, customer repo, etc

    Also counted in Docs outside teams/projects
  • Darshen@darshen

    1. Claude Docs for Linear. 2. Google Drive organization for Linear. 3. Prototype / HTML / MD files embedded.

    Also counted in Rich media and embeds, Linking docs to work
  • Concepts - Concept distillation, tagging - Aliases, deprecation, and redirects - Bounded contexts or namespaces - Definition lifecycle and review Relations - Core relation types (subconcept_of, constrains, subsumes) - Extensible relation vocabulary - Composition rules - Relation proliferation linting Integrity and freshness - Built-in staleness / out-of-sync jobs - Consistency linting - Code anchoring Issues integration - Bidirectional issue sync - Provenance and decision records Navigation and analysis - Graph view stratified by tag - Impact analysis - Temporal views

    Also counted in Staleness and freshness, Linking docs to work
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
  1. 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.
  2. Patch APIs alone make edits smaller, but they still let unreviewed agent changes land silently in docs people rely on.
  3. 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
  1. Should agent edits default to proposals that need human approval, or apply directly with an easy revert?
  2. How lossy is the current markdown round-trip today, and which constructs like tables, nested lists, and comments break most often?
  3. Do teams want docs synced to their repos, or do they only want history and diffs that their agents can read?
26 replies
  • markdown files that agents can read and edit without a copy paste step

  • John Rood@johnroodepic

    Give every doc read a revision ID and let API writes require that revision. If I edit a paragraph while an agent is working, its stale write should fail, not quietly undo mine.

    Also counted in Staleness and freshness
  • Garrett@pacificdaemon

    Patched based APIs and mcps so agents can make targeted edits without rewriting the whole file

  • Keith Zhai@KeithZhai

    raw markdown at a stable url

    Also counted in Sharing with non-Linear users
  • it should be possible to integrate linear docs via api and cli with github actions and things and it should properly support bidirectional sync - which is doesn’t now. it shouldn’t change paragraphs that were not touched. so diff should be clean and show only what relay changes by user

    Also counted in Git-backed docs
  • CryptoPraetoria@CryptoPraetoria

    I use linear as my single source of truth because it just works perfectly beside my hindsight agents memory. I love linear. But I think I can be improved. Some of the features are only ui only instead of mcp

  • working using api should work. updating document using api should not reset position of the comments. so ui flow should match api. and it should be usable for people and agents. ui placement for document is really bad. not possible to find them in menu.

    Also counted in Doc organization and findability
  • rahul@withqwerty1 like

    would be nice to collaborate with agent in-document, a bit like how link works

  • Rohan@proxy_vector

    Version history that an agent can diff would help most, since that is how a team sees what changed after an agent edits a doc.

    Also counted in Version history and suggested edits
  • Linards Liepenieks@LLiepenieks

    agent edits as reviewable diffs on docs, like code

    Also counted in Version history and suggested edits
  • Máté Rauscher@rauschermate

    native markdown support, so I can view/edit/comment on docs my agent is making. shouldn't need an mcp for that, let it live locally and then sync to linear like dropbox

  • anton 🇺🇦🇺🇦🇺🇦@podviaznikov· replying to @karrisaarinen

    another one - it should be possible to use git cli to clone all the docs maybe even tickets and push back too. i see no reason why you cannot add git protocol support as one of the interfaces. then any agent can see history of docs push and diff etc for free with no new tooling.

    Also counted in Git-backed docs, Version history and suggested edits
  • anton 🇺🇦🇺🇦🇺🇦@podviaznikov· replying to @karrisaarinen

    eg can you have markdown doc locally and edit with any editor and then ask agent to push to linear updates does it work as you expect it to work?

  • Jeff Wayne@jeffwjeffw

    the linear diff/review flow but native for documents. thus can iterate artifacts with agents for non-code workflows

    Also counted in Version history and suggested edits
  • Moiz K. Malik@moizkmalik

    For me, it’s two things. The interface for adding documents is clunky it’s really meant as a wiki style list and you can’t update it over mcp. The other issue is that you can’t really chat against it. What I want is non tech people can ask questions of the code/docs.

  • MarkRead@MarkReadPro

    Clean round-tripping would be huge: paste markdown in, export the same markdown out, without tables or nested lists getting mangled.

  • Why? this belongs in an orchestrator/agent harness. A dedicated git repo for agent skills and product planning, which holds your worktrees, and checks out your git repos as submodules.

  • Steven Chen@_stevenchen

    overall, keeping docs current takes a tremendous amount of manual effort; we need a way for agents to propose updates that humans can review.

    Also counted in Version history and suggested edits
  • Hexabl0b@hexablob

    i'd want to approve an agent's diff before it becomes the team's docs. could agents have permission to propose edits without permission to publish them?

    Also counted in Permissions inside workspace, Version history and suggested edits
  • you don’t need to do git hosting, just adopt git protocol on top of rest api and mcp

    Also counted in Git-backed docs, Version history and suggested edits
  • Danny@mrniach

    a2ui + mcp ui support. i wanna create my own integration for my team which doesnt need to go through linear approvals

  • Aidan Sunbury@aidansunbury

    There needs to be good flows of making docs git backed! I should be able to make a PR to make chances to my linear docs so that it can go through all my normal review flows and have native git based histories

    Also counted in Git-backed docs, Version history and suggested edits
  • Manan@manan_suneja

    I'm starting to manage projects in linear and one of the gaps I noticed was the ability for me to connect context with work/task mgmt. right now setup is my agent reading context from local md files(obsidian) and updating linear with task status and dates

    Also counted in Linking docs to work
  • self updating based on Slack, Github, Linear

    Also counted in Linking docs to work
  • thedres@AndresM54324611

    A space for highly visual documentation rather than prose-heavy content. Agents can easily spin up this type of documentation if allowed, and it’s much easier to digest context across sessions; especially for ADRs, Design, and Product flows. I have been using a TLDraw board with tldrawoffline as the space, since it’s quite easy to do this. Something similar or a connection in Linear would be amazing.

    Also counted in Rich media and embeds
  • Dott@DottChen· replying to @karrisaarinen

    proactiveness supported by linear agent in slack?

    Also counted in Linking docs to work
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
  1. Two-way links alone solve where a doc lives, not whether it is still accurate, which @ItsPatrickU and @sanketpath flag as the real pain.
  2. Project-bound docs die when the project ships, so linking them harder to projects deepens the staleness problem rather than fixing it.
  3. 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
  1. Do teams actually want the agent to edit docs when linked work changes, or only to flag drift for a human?
  2. Is the spec-before-work doc a separate object, or should it simply be the issue or project description that agents read?
  3. How many teams already keep decision logs in Notion or Obsidian, and would linking to them be enough instead of moving them?
17 replies
  • Cameron Turner@camdesignstuff

    The doc I want next to every issue is 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. Do docs and issues link both ways?

  • Amazing! - Home for documents to create/find them easily - Carousals for attachments - Annotate images cos this in itself is a great - documentation for agents - One-click link related issues/PRs - surface if issues/prs moved ahead but doc is stale - Copy as markdown with link included

    Also counted in Staleness and freshness, Rich media and embeds, Doc organization and findability
  • Ben Adelson@BenAdelson

    Documents for projects, ideas, marketing docs/skills, decision trees Related to customers like case studies by customer, maybe more for CS teams to manage communications Easier way to view documents by issue or project.

    Also counted in Doc organization and findability
  • oorestisime@oorestisime

    Personal workspaces, templates, indexing searching (big pain) and connecting nodes, connected issues/prs.

    Also counted in Templates, Docs outside teams/projects, Doc organization and findability
  • PatrickUllrich@ItsPatrickU

    Linear docs are a great decision/delta log, but they're tied to projects and go stale once they ship. What I want is internal docs for the product as it is today, like "how to set up a client on this integration," linked back to the projects that built it. Team docs could theoretically be a place but that’s assuming a lot about the org structure.

    Also counted in Docs outside teams/projects, Staleness and freshness
  • Faqih Muntashir@itsfaqih_

    Confluence -> Linear sync

  • Dott@DottChen· replying to @karrisaarinen

    proactiveness supported by linear agent in slack?

    Also counted in Agent and API editing
  • Roy Pereira@roypereira

    Last we talked that we want a decision log in Linear when teams make a decision in Slack. Could be nice if we can ask the Linear bot to log the decision.

  • Semantic binding to and at linear primitives

  • Manan@manan_suneja

    I'm starting to manage projects in linear and one of the gaps I noticed was the ability for me to connect context with work/task mgmt. right now setup is my agent reading context from local md files(obsidian) and updating linear with task status and dates

    Also counted in Agent and API editing
  • Concepts - Concept distillation, tagging - Aliases, deprecation, and redirects - Bounded contexts or namespaces - Definition lifecycle and review Relations - Core relation types (subconcept_of, constrains, subsumes) - Extensible relation vocabulary - Composition rules - Relation proliferation linting Integrity and freshness - Built-in staleness / out-of-sync jobs - Consistency linting - Code anchoring Issues integration - Bidirectional issue sync - Provenance and decision records Navigation and analysis - Graph view stratified by tag - Impact analysis - Temporal views

    Also counted in Staleness and freshness, Doc organization and findability
  • Jonathan@jhogervorst

    I think you should allow lots of flexibility when using the content. Like referring to (or embedding) a specific part of a doc elsewhere, without copying it. Or moving a section to another place (same or different doc), while keeping the history and comments alive.

  • self updating based on Slack, Github, Linear

    Also counted in Agent and API editing
  • Darshen@darshen

    1. Claude Docs for Linear. 2. Google Drive organization for Linear. 3. Prototype / HTML / MD files embedded.

    Also counted in Rich media and embeds, Doc organization and findability
  • Pipe Gilinski ᯅ@pipegilinski

    good question! ... make the Linear<->Notion the perfect and seemless integration

  • Make docs that span projects. Let me embed things like Whimsical boards, etc Suggested changes

    Also counted in Rich media and embeds, Docs outside teams/projects, Version history and suggested edits
  • That is one missing component for Linear. link

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
  1. Folders and personal workspaces fix where a doc lives, but @paulozoom and @ItsPatrickU say the bigger pain is docs going stale.
  2. A full org, team, and personal hierarchy like @PeterSkott describes would rebuild Notion inside Linear and dilute the issue-tracking core.
  3. 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
  1. Will unfiled, author-owned workspace docs stay findable, or does the Linear Agent need to suggest a home for each one quickly?
  2. Can project links and agent-driven review solve staleness, for example by flagging docs whose linked work has changed?
  3. If Linear does nothing, does losing personal drafts and living docs to Notion weaken Linear's role as the context source for agents?
16 replies
  • Judah Guttmann@judahguttmann2 likes

    My biggest ask is a place to draft documents in a personal workspace. Not everything is a project from day one.

  • Michael Kern@michaelhkern

    - Personal docs (which can later be moved to team/public docs) - Agent documentation - Copy as markdown - Standalone docs (don't need to be default-linked to a project or initiative) ...Just let us know when the Confluence import assistant is ready!

  • Julian LaNeve@JulianLaneve· replying to @karrisaarinen

    personal documents would solve a lot of what I need, my workflow would prob be: - upload a personal doc - share that via link (I don’t care if other people can see it / don’t really need sharing perms) - eventually move it to a team if it belongs there

    Also counted in Sharing with non-Linear users
  • adam smielewski@AdamSmielewski

    Can we make a document a standalone item not tied to project / ticket? I often make a ticket to create a doc and then I have to link / find the ticket instead of linking the doc around.

  • Personal docs so I don't need a different tool for that.

  • Make docs that span projects. Let me embed things like Whimsical boards, etc Suggested changes

    Also counted in Rich media and embeds, Version history and suggested edits, Linking docs to work
  • Tim@timfl93

    - Workspace level Documents page (all documents you can access) with ways to create pages to structurally surface them (wiki) - Document ownership flow (e.g. set responsibility for content, edit / approval?) - Personal documents I can share with others not tied to teams

    Also counted in Doc organization and findability, Permissions inside workspace
  • PatrickUllrich@ItsPatrickU

    Linear docs are a great decision/delta log, but they're tied to projects and go stale once they ship. What I want is internal docs for the product as it is today, like "how to set up a client on this integration," linked back to the projects that built it. Team docs could theoretically be a place but that’s assuming a lot about the org structure.

    Also counted in Linking docs to work, Staleness and freshness
  • Saad Salman@thesaadsalman

    Making a Document within a Project is fine, but sometimes I make a document independently and then attaching it to the Project is a hassle. And trying to look for Documents not in a project, other than using Search, also difficult - I have to go to the Org page?

    Also counted in Doc organization and findability
  • Paulo@paulozoom

    couple more - workspace level docs, not in any one team - the million dollar need: solve the junk/stale drawer problem that inevitably happens with team docs. most of our notion is out of date and nobody’s got the time to figure out what’s still relevant and not, it’s a mess.

    Also counted in Staleness and freshness, Doc organization and findability
  • oorestisime@oorestisime

    Personal workspaces, templates, indexing searching (big pain) and connecting nodes, connected issues/prs.

    Also counted in Linking docs to work, Templates, Doc organization and findability
  • nested docs - today they can only be in a Project or Team. We want to build out a Knowledge base, customer repo, etc

    Also counted in Doc organization and findability
  • Julian LaNeve@JulianLaneve

    home for documents outside of teams - not everything necessarily belongs to a team I’ve actually started using linear for this a bunch. local agent hooked up to linear MCP works wonders, esp bc you can make edits without messing w comments. but “where to put it” becomes awkward

  • Should be org->team->personal markdown knowledge in a folder structure in that order each level you should be able to define a set of categories you want to sort context into, with a jev type model. There should be a context half-life decay for all docs that provides a lifecycle

    Also counted in Staleness and freshness, Doc organization and findability
  • Steven Chen@_stevenchen· replying to @nikstep

    Suggested changes 😂

    Also counted in Rich media and embeds, Version history and suggested edits
  • PatrickUllrich@ItsPatrickU

    Be curious just how far you want to go with docs. Just docs for product or the entire company (notion) / external customers (mintlify etc)?

    Also counted in Sharing with non-Linear users
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
  1. Copying the full Google Docs permission model would turn a narrow review need into a sprawling access-control system.
  2. Most askers mean coworkers without seats, not the public internet, so @nkrekow and @mccun934 describe a seat-cost problem more than a publishing problem.
  3. 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
  1. 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?
  2. Does free commenting by non-seat users cannibalize paid seats, and where should the line between commenting and editing sit?
  3. Should the shareable unit be a document, or any project brief and issue view, as @joesaunderson suggests?
12 replies
  • Sharing links like Google Docs would be killer! Context: we use team docs internally but have lots of clients and would be great to just share a link with them or let anyone with access comment on docs.

  • being able to share docs with those outside of linear - not necessarily for editing but at least viewing ideally commenting - it’s one of the big reasons we use gdocs over linear docs so teams who don’t use linear can review (anyone outside of product/design/eng) the other request being better organization they are too hard to find today

    Also counted in Doc organization and findability
  • Austin Kettner@austinkettner

    Ability to share documents externally would be a huge upgrade, with customizable share perms.

  • Isaiah Dahl@isaiahdahl· replying to @karrisaarinen

    same request for me. I'd like the same mental model as google docs. Share with specific emails (inside or outside org) and anyone with the link; viewer, commenter, editor access.

  • Abdul Q.@abdul_quadir_a

    any chance of a guest view for client docs agencies share handover docs with marketing teams who will never get a seat

  • Sameer Bhalla@sambhall· replying to @karrisaarinen

    The external sharing is the one use case we keep notion around for. Would LOVE external sharing capabilities.

  • Joe Saunderson@joesaunderson· replying to @karrisaarinen

    I would like this for project/issues too... I often have internal users asking for a project brief... but I don't want to pay for a seat for them to have a glance. Almost like the Vercel viewer seats

  • Julian LaNeve@JulianLaneve· replying to @karrisaarinen

    personal documents would solve a lot of what I need, my workflow would prob be: - upload a personal doc - share that via link (I don’t care if other people can see it / don’t really need sharing perms) - eventually move it to a team if it belongs there

    Also counted in Docs outside teams/projects
  • nick krekow@nkrekow· replying to @karrisaarinen1 like

    internally would satisfy our needs for anyone at the company who isn’t a linear user…while would love for everyone to use linear just not gonna happen at least at this point in time and can’t justify getting paid seats just to view product briefs when gdocs exists for free

  • Mike McCune@mccun934· replying to @nkrekow

    agree with this. trying to get away from Notion but the license restrictions for sharing documents were a blocker for us

  • Keith Zhai@KeithZhai

    raw markdown at a stable url

    Also counted in Agent and API editing
  • PatrickUllrich@ItsPatrickU

    Be curious just how far you want to go with docs. Just docs for product or the entire company (notion) / external customers (mintlify etc)?

    Also counted in Docs outside teams/projects
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
  1. Version history alone is a passive log, and nobody reads logs after an agent quietly rewrites a spec.
  2. Git-backed docs, as @podviaznikov and @aidansunbury suggest, serve engineers but exclude the PMs and designers who write most docs.
  3. 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
  1. Should human edits default to direct writes while agent edits default to proposals, or should each team choose?
  2. Is the bigger pain reviewing agent edits or keeping docs current, as @_stevenchen describes, which would mean agents must also proactively propose updates?
  3. How often do teams actually lose work to concurrent overwrites, as @jackonawalk reports, and is that a separate editor bug?
12 replies
  • Rohan@proxy_vector

    Version history that an agent can diff would help most, since that is how a team sees what changed after an agent edits a doc.

    Also counted in Agent and API editing
  • Aidan Sunbury@aidansunbury

    There needs to be good flows of making docs git backed! I should be able to make a PR to make chances to my linear docs so that it can go through all my normal review flows and have native git based histories

    Also counted in Git-backed docs, Agent and API editing
  • Hexabl0b@hexablob

    i'd want to approve an agent's diff before it becomes the team's docs. could agents have permission to propose edits without permission to publish them?

    Also counted in Permissions inside workspace, Agent and API editing
  • Jeff Wayne@jeffwjeffw

    the linear diff/review flow but native for documents. thus can iterate artifacts with agents for non-code workflows

    Also counted in Agent and API editing
  • Jack@jackonawalk

    Better concurrent editing. We’ve ran into scenarios where people overwrite others’ changes. Suggestion mode.

  • wiretransfer@wiretransfer

    also version history

  • Steven Chen@_stevenchen

    overall, keeping docs current takes a tremendous amount of manual effort; we need a way for agents to propose updates that humans can review.

    Also counted in Agent and API editing
  • Linards Liepenieks@LLiepenieks

    agent edits as reviewable diffs on docs, like code

    Also counted in Agent and API editing
  • Make docs that span projects. Let me embed things like Whimsical boards, etc Suggested changes

    Also counted in Rich media and embeds, Docs outside teams/projects, Linking docs to work
  • anton 🇺🇦🇺🇦🇺🇦@podviaznikov· replying to @karrisaarinen

    another one - it should be possible to use git cli to clone all the docs maybe even tickets and push back too. i see no reason why you cannot add git protocol support as one of the interfaces. then any agent can see history of docs push and diff etc for free with no new tooling.

    Also counted in Git-backed docs, Agent and API editing
  • you don’t need to do git hosting, just adopt git protocol on top of rest api and mcp

    Also counted in Git-backed docs, Agent and API editing
  • Steven Chen@_stevenchen· replying to @nikstep

    Suggested changes 😂

    Also counted in Rich media and embeds, Docs outside teams/projects
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
  1. A time-based staleness badge or half-life decay flags old docs that are still true and misses new docs that are already wrong.
  2. A flag only tells people a doc is stale, and @paulozoom says nobody has time to fix stale docs anyway.
  3. 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
  1. 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?
  2. 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?
  3. Will doc owners actually review agent-drafted updates, or do the updates need to ship as auto-applied edits with an undo?
9 replies
  • Should be org->team->personal markdown knowledge in a folder structure in that order each level you should be able to define a set of categories you want to sort context into, with a jev type model. There should be a context half-life decay for all docs that provides a lifecycle

    Also counted in Doc organization and findability, Docs outside teams/projects
  • Paulo@paulozoom

    couple more - workspace level docs, not in any one team - the million dollar need: solve the junk/stale drawer problem that inevitably happens with team docs. most of our notion is out of date and nobody’s got the time to figure out what’s still relevant and not, it’s a mess.

    Also counted in Docs outside teams/projects, Doc organization and findability
  • Amazing! - Home for documents to create/find them easily - Carousals for attachments - Annotate images cos this in itself is a great - documentation for agents - One-click link related issues/PRs - surface if issues/prs moved ahead but doc is stale - Copy as markdown with link included

    Also counted in Linking docs to work, Rich media and embeds, Doc organization and findability
  • arix.online@arix_online3 likes

    Templates and placeholder text. I really love how Slite implemented this and surprised it’s still not a thing in Notion Templates that can be spun up with just placeholder slots people edit means the structure doesn’t decay over time Also, staleness indication

    Also counted in Templates
  • Concepts - Concept distillation, tagging - Aliases, deprecation, and redirects - Bounded contexts or namespaces - Definition lifecycle and review Relations - Core relation types (subconcept_of, constrains, subsumes) - Extensible relation vocabulary - Composition rules - Relation proliferation linting Integrity and freshness - Built-in staleness / out-of-sync jobs - Consistency linting - Code anchoring Issues integration - Bidirectional issue sync - Provenance and decision records Navigation and analysis - Graph view stratified by tag - Impact analysis - Temporal views

    Also counted in Linking docs to work, Doc organization and findability
  • Steven Chen@_stevenchen

    - project docs are a flat list of links with no clear signal for what’s current or important - human-readable decisions get mixed with agent-generated specs - decisions made in PRs, tickets, & comments are hard to find later as a coherent explanation of why we built something

    Also counted in Doc organization and findability
  • John Rood@johnroodepic

    Give every doc read a revision ID and let API writes require that revision. If I edit a paragraph while an agent is working, its stale write should fail, not quietly undo mine.

    Also counted in Agent and API editing
  • Brandon Waselnuk@BrandonWaselnuk

    does this also have an undead campaign for the ADR from 2021 no one cleaned up?

  • PatrickUllrich@ItsPatrickU

    Linear docs are a great decision/delta log, but they're tied to projects and go stale once they ship. What I want is internal docs for the product as it is today, like "how to set up a client on this integration," linked back to the projects that built it. Team docs could theoretically be a place but that’s assuming a lot about the org structure.

    Also counted in Docs outside teams/projects, Linking docs to work
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
  1. Building "embed anything" pushes docs toward a Notion-style block editor and erodes the plain markdown that agents and the API rely on.
  2. An iframe of a Whimsical or tldraw board shows the content to people, but agents cannot read it, so the context stays outside Linear.
  3. 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
  1. Are most of these visual artifacts agent-generated HTML, or are they hand-made boards in Whimsical and tldraw?
  2. Do agents need to edit embedded artifacts, or is reading a text summary of them enough?
  3. How often does the visual need to render inline, and how often would a rich link preview cover the job?
10 replies
  • Make docs that span projects. Let me embed things like Whimsical boards, etc Suggested changes

    Also counted in Docs outside teams/projects, Version history and suggested edits, Linking docs to work
  • wiretransfer@wiretransfer

    MEDIA images, videos, any size, any position, easy to annotate, link to source, etc. also comments

  • Steven Chen@_stevenchen

    oh and allow embed for htmls please increasingly artifacts/prototypes are being shared in this fashion, being able to embed one directly would be amazing.

  • Not Theo@hottakeweekly

    Being able to build more rich plans like link. Anything to help visualize the shape of projects (architecture, mock ups, interactive state machines).

  • thedres@AndresM54324611

    A space for highly visual documentation rather than prose-heavy content. Agents can easily spin up this type of documentation if allowed, and it’s much easier to digest context across sessions; especially for ADRs, Design, and Product flows. I have been using a TLDraw board with tldrawoffline as the space, since it’s quite easy to do this. Something similar or a connection in Linear would be amazing.

    Also counted in Agent and API editing
  • Amazing! - Home for documents to create/find them easily - Carousals for attachments - Annotate images cos this in itself is a great - documentation for agents - One-click link related issues/PRs - surface if issues/prs moved ahead but doc is stale - Copy as markdown with link included

    Also counted in Linking docs to work, Staleness and freshness, Doc organization and findability
  • cviva@sea_viva

    The problem for me with notion is that it doesn’t support company branded documentation For instance we may use notion to draft a statement of work, but then we have to export somewhere else to get a company branded version, then store that somewhere else Having markdown live in an environment with non markdown files (PDFs, decks, etc) would be huge. Even “tying” them together would be even cooler (markdown — pdf)

  • Ivan@ivbobrov1 like

    Like for the picture 🤌

  • Darshen@darshen

    1. Claude Docs for Linear. 2. Google Drive organization for Linear. 3. Prototype / HTML / MD files embedded.

    Also counted in Linking docs to work, Doc organization and findability
  • Steven Chen@_stevenchen· replying to @nikstep

    Suggested changes 😂

    Also counted in Docs outside teams/projects, Version history and suggested edits
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
  1. A per-doc view and edit permission matrix adds configuration that Linear's open-by-default workspace has deliberately avoided.
  2. Most replies describe fear of accidental edits (@paulozoom, @Roywulms), which ownership and history solve better than access control.
  3. 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
  1. Are accidental edits to policy docs actually happening, or is the lock request mostly about reassurance?
  2. Do teams need the draft history wiped on publish, as @paulozoom asked, or is hiding it from viewers enough?
  3. Should agents edit published docs only through owner-approved proposals, or are direct agent edits acceptable with clear attribution?
5 replies
  • Paulo@paulozoom3 likes

    - some organization: folders, sections, or nested docs - private docs shared only b/w a few people. some docs start private, then open up later to all (history wipe pls) - lock for edits, just to avoid accidental edits

    Also counted in Doc organization and findability
  • Hexabl0b@hexablob

    i'd want to approve an agent's diff before it becomes the team's docs. could agents have permission to propose edits without permission to publish them?

    Also counted in Version history and suggested edits, Agent and API editing
  • - Document permissions (view vs edit) - Organize documents (with labels? Folders?) At the moment, we organize our policies in Linear. It actually works very well, if you find a good structure. But the docs are hard to find and everyone can edit them.

    Also counted in Doc organization and findability
  • DJ Brinkerhoff@djbrinkerhoff

    making them read only linking docs together/having parent child relationships

    Also counted in Doc organization and findability
  • Tim@timfl93

    - Workspace level Documents page (all documents you can access) with ways to create pages to structurally surface them (wiki) - Document ownership flow (e.g. set responsibility for content, edit / approval?) - Personal documents I can share with others not tied to teams

    Also counted in Docs outside teams/projects, Doc organization and findability
TemplatesDoc templates with placeholder text that shows what to fill in.4 people

Doc templates with placeholder text that shows what to fill in.

5 replies
  • arix.online@arix_online3 likes

    Templates and placeholder text. I really love how Slite implemented this and surprised it’s still not a thing in Notion Templates that can be spun up with just placeholder slots people edit means the structure doesn’t decay over time Also, staleness indication

    Also counted in Staleness and freshness
  • Sandi@L47HAHA

    Having a good way to do weekly’s. Maybe templates like you can have for bugs. Having the ability to have have folders

    Also counted in Doc organization and findability
  • oorestisime@oorestisime

    Personal workspaces, templates, indexing searching (big pain) and connecting nodes, connected issues/prs.

    Also counted in Linking docs to work, Docs outside teams/projects, Doc organization and findability
  • arix.online@arix_online· replying to @jamiequint1 like

    Templated headers and sections aren't quite enough tho 😅 I like the placeholder text solution that @slitehq provides. It gives signal as to what is expected to be filled in, especially in broad content umbrellas. Today, I resort to adding Callouts in Notion templates to hint at what should be written and then delete it lol

  • Pythonics@pythonics00

    Enable gang prompting please

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
  1. 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.
  2. PR-based review, as @aidansunbury asked for, may really be a request for change review and history inside Linear rather than for GitHub specifically.
  3. 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
  1. Do the lossy API diffs that @podviaznikov describes come from how we convert markdown, and how many agent-driven teams hit this problem?
  2. Would in-Linear suggested changes with a review step satisfy people who asked for PRs, or do they specifically need GitHub's review tooling?
  3. 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?
5 replies
  • Aidan Sunbury@aidansunbury

    There needs to be good flows of making docs git backed! I should be able to make a PR to make chances to my linear docs so that it can go through all my normal review flows and have native git based histories

    Also counted in Version history and suggested edits, Agent and API editing
  • anton 🇺🇦🇺🇦🇺🇦@podviaznikov· replying to @karrisaarinen

    another one - it should be possible to use git cli to clone all the docs maybe even tickets and push back too. i see no reason why you cannot add git protocol support as one of the interfaces. then any agent can see history of docs push and diff etc for free with no new tooling.

    Also counted in Agent and API editing, Version history and suggested edits
  • Isaiah Dahl@isaiahdahl

    Primary friction I have is around how documents can be organized. - Make documents a more first party entity (not just a resource type) I want to see "Documents" in the sidebar - Teams have a "Documents" tab, Projects have Resources that are just a list of links, one could be a external link, one could be a document, but then Team Home organizes documents by project? - Documents page in Team feels like an issues list. Something about that mental model doesn't feel like the right home for all my documents. - Connect a repo and view all the .md files organized like they are in code. Maybe read only?

    Also counted in Doc organization and findability
  • you don’t need to do git hosting, just adopt git protocol on top of rest api and mcp

    Also counted in Agent and API editing, Version history and suggested edits
  • it should be possible to integrate linear docs via api and cli with github actions and things and it should properly support bidirectional sync - which is doesn’t now. it shouldn’t change paragraphs that were not touched. so diff should be clean and show only what relay changes by user

    Also counted in Agent and API editing
One-offsAsks no one else made19 people

Asks no one else made

  • Bri Angulo@briangulo_1 like

    Anything that makes my team switching from google docs 😅

  • i think the most important thing is your own team uses linear docs for all and not other docs. then you will see all the issues. for now they are unusable and posted about it on other comment.

  • I find the mobile app difficult to navigate, switching projects/teams and finding relevant issues, sorting filtering very confusing - I didn't realize how difficult it was till recently as i work more and more on the go. Love linear otherwise, keeps me sane.

  • Gordon McCreight@gmccreight

    Here's my list of considerations: link

  • avv@avithaldas

    (1) differential human vs agent targeted sections (2) synthesis of the code on a periodic basis so that the agents dont need to read the full code all the time to work (3) Clear principles based onboarding. E.g. each project starts with design principles (E.g. design.md) , arch principles, DB princples. So that all code edits made any any user follows the right guidelines (4) automatic conflict resolutions , and proactive flagup (5) ability to define goals, which each lower dimension of the hierarchy can keep reconciling to, to callout discrepancies and conflicts.

  • Yakko@yakkomajuri1 like

    read: what do you need for linear to replace notion link

  • anton 🇺🇦🇺🇦🇺🇦@podviaznikov· replying to @karrisaarinen

    ok, so when you want to share doc with someone? how do you even find it in ui? or see their comments after the commented and you repushed? maybe you fixed those flows recently, but when i was testing it and tried to migrate people from google docs to linear docs all the major flows were broken

  • Fred Oliveira 🧠@f· replying to @paulozoom

    love those, but assuming revisions (a must have, imho), locking for edits is just adding friction a % of the time, no?

  • Paulo@paulozoom· replying to @f

    I make frequent unintentional edits in issues due to pressing letter-based shortcuts. Just a nice to have for popular docs to prevent that, not a must.

  • Eric@ericwithcoffee1 like

    Strong support for skills, as they’re essentially just a type of doc that sometimes includes code. Notion recently introduced this and it’s been a great addition.

  • AXIALIS | Desktop App Tools@AxialisSoftware· replying to @karrisaarinen

    That difference is revealing: the first-party agent may encode workflow context that the API and MCP surface do not expose

  • Yousef Amirghofran@YAmirghofran

    We need some sort of chat

  • angelo@giaccoangelo1 like

    code + the product vision is the source of truth on top of the codebase i need a simple -architecture.md -vision.md for longer context reasoning not convinced i'd store this in linear but that's my setup:)

  • Mike Grouchy@mgrouchy

    give me a way to import them from confluence, so I can delete that subscription.

  • Dott@DottChen· replying to @karrisaarinen

    how about memory? any plans on working on that too?

  • pristine@pristinemon

    used to love linear now its just a waste of time ;/

  • Radek Sienkiewicz@velvet_shark

    Oh, that would be a great improvement to my current workflow where I need to update everything in a project description. link

  • we moved from gdocs to linear because they didn't have markdown support but now that there's .md support... link

  • alex@alx_andru

    Having documents verified for context retrieval or prioritized. Just because something is written in a document doesn't mean it should be picked up by context and followed for an Agent to take as instructions.

  • Saad Salman@thesaadsalman

    Documents feel like a second-class citizen. I was on a huddle with a coworker where we were going over a document I had made and he was like “how do you even make a document in Linear?” And I showed him File > New > Document, which seems to be the quickest way

Praise and asidesExcitement, jokes, and questions about the project32 replies

Excitement, jokes, and questions about the project

  • Is the internal name Lotion?

  • Martin Slaney@martinslaney1 like

    This is an example of software teams should build for themselves. Documentation = context that should be platform and agent agnostic.

  • Lorenzo Dossi@lorenzodossi

    cc @giaccoangelo

  • Dott@DottChen

    i smell war

  • andrew@asbd_me

    there's a real teams product here link

  • andrew@asbd_me

    wild style diagram but you’ll see it. link

  • Jarmo@jarmovalmari

    Ideally, ”Lotion” replaces Notion for product specs and permanent product knowledge. It would be used as the source of truth, helping anyone and their agents (Claude/Claude Design & Linear) build correctly on top of the customer’s product. Tidy, well-organized product foundation.

  • Jamie Quint@jamiequint· replying to @arix_online1 like

    link does this fwiw

  • feeling like arthas menethil rn

  • Anvisha@anvisha

    I’m glad you guys are investing here! Linear docs are so slept on.

  • Simon Almers@SimonAlmers

    FINALLY.md have been waiting for this for ages! 🕺🏻✨

  • Isaiah Dahl@isaiahdahl

    There's some awesome nice to have craft features in here. link

  • Eduard@iconoise

    hahaha dota 4 life :D

  • Julian LaNeve@JulianLaneve

    worth noting I wouldn’t imagine this replacing Google Docs, this would be just product/eng stuff. Replacing something like google docs is tough bc then the entire co needs access to + actively choose linear as a gdocs replacement

  • Paulo@paulozoom· replying to @jorilallo1 like

    please hurry, our notion yearly renewal is up soon lol

  • Dave Nunez@capitaltruist3 likes

    If you want the best docs option, shaped by lessons learned from building the docs tools at Stripe, check out @falconer_ai We have a great linear integration

  • Meshary@MesharyTB

    FINALLLLYYYYYY THE MISSING PIECE SO WE CAN FULLY MOVE TO LINEAR

  • Benjamin Ottensten@benjavo· replying to @YAmirghofran

    The linear agent is there…

  • Niklas Stephenson@nikstep· replying to @_stevenchen

    I will die on that hill

  • Steven Chen@_stevenchen· replying to @nikstep

    i am with you now and i regret it to this day

  • Niklas Stephenson@nikstep· replying to @_stevenchen1 like

    Welcome to manager life 😂

  • Ben King@benkingfm

    I'd take inspiration from Cloudflare OS

  • Olav@OlavSindre

    Tides of Darkness > WOW

  • Sriram@tsriram

    i see your notion here

  • Lotta folks gonna be competing to own this for you. link

  • Adrianne Stone 👩🏻‍💻🚀🍻@dradriannestone· replying to @karrisaarinen

    I just saw that! 🙌🙌🙌

  • Fletcher Richman@fletchrichman

    And they are all on a collision course :) link

  • Máté Rauscher@rauschermate

    funny how twitter works, just after I posted, this was the next tweet I saw: link

  • Brandon Waselnuk@BrandonWaselnuk· replying to @karrisaarinen

    By the light!

  • Noel Sequeira@noelsequeira

    The world, if Linear and Notion could only get along link link

  • Dale@ddaalee

    link

  • Alex@alexgilev

    "World of Documents"

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.

DefaultOwnerSeen byLives inCost
PersonalYouYouYour spaceHidden by default, so it can't be found, and every person grows their own stale drawer
Team (today)The teamWorkspaceA teamYou pick a team before you know one; some docs belong to none
WorkspaceNobodyWorkspaceWorkspaceVisible but unowned, which is how wikis rot
Unfiled, ownedYouWorkspaceNowhere yetNeeds 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."

ApproachKeeps your editsReviewableFrictionAsked for by
Overwrite (the API today)NoNoNoneNobody
Edit locksYesNoHigh@paulozoom
Revision-checked patchesYesPartlyLow@johnroodepic, @pacificdaemon
Agent edits as proposalsYesYesOne click@LLiepenieks, @_stevenchen, @jeffwjeffw
Git and PRsYesYesHigh 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:

  1. The agent reads the doc at revision 12.
  2. You edit a paragraph, so the doc is now at revision 13.
  3. The agent writes "only if still at 12" and is turned away.
  4. 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."

SignalEffortFalse alarmsWhat it catches
Age, a half-life (@PeterSkott)NoneManyOld docs, including stable ones that are still right
Owner review (@timfl93)A choreFewWhatever the owner remembers to check
Linked work changedNoneSomeDocs whose subject shipped or moved
Agent proposes the fix (@_stevenchen)One reviewSomeThe 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:

  1. Linear flags the doc as possibly out of date.
  2. The Linear Agent drafts the update as a diff.
  3. 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).

OptionColleaguesClientsAdminSeat risk
Per-email roles (@isaiahdahl)YesYesHighLow
Free company viewers (@joesaunderson)YesNoNoneSome
Public link (@aesadde)YesYesNoneLow
Client guests (@abdul_quadir_a)NoYesSomeLow

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."

WhoReadCommentEdit
Anyone with a company emailFreeFreeNeeds a seat
Anyone with the public linkYesNoNo

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.