Linear Documents
Issues track tasks, but teams need space for longer writing: plans, specifications, meeting notes, and decisions. Linear documents give that writing a home right beside the work. Readers open the document from the same project that holds the issues.
Why Documents Matter
Context gets lost when plans live in separate tools. A developer who reads an issue wants the background without searching through other apps. Documents inside Linear keep the plan, the discussion, and the tasks together.
Everyday Comparison
Picture a binder for a home renovation. The checklist of tasks sits in the front. Behind it sit the floor plan, the budget, and the notes from the contractor. Linear issues act as the checklist, and documents act as the pages behind it.
PROJECT: Customer Portal
│
├── Issues
│ ├── ENG-301 Build login page
│ └── ENG-302 Build invoice list
│
└── Documents
├── Product Requirements
├── Technical Design
└── Meeting Notes - Kickoff
Where Documents Live
| Location | Best Use |
|---|---|
| Project | Requirements, designs, and decisions for one deliverable |
| Team | Working agreements, onboarding guides, and process notes |
| Issue | Detailed notes that explain one task |
The exact places available can differ by plan and by product updates, so check your workspace for current options.
Create a Document
- Open the project, team, or issue where the document belongs.
- Choose the option to add a document.
- Type a title.
- Write your content in the editor.
The editor supports headings, lists, tables, code blocks, and images. It accepts Markdown-style shortcuts, so typing a pound sign at the start of a line creates a heading.
Link Documents and Issues
Type an issue identifier such as ENG-301 inside a document to link it. Readers click the link and jump to the task. Paste a document link into an issue description to give developers the background they need.
Collaborate
Mention Teammates
Type the at sign followed by a name to notify a colleague. The person receives an inbox notification with a link.
Add Comments
Select text and leave a comment to start a discussion on a specific sentence. Resolve the thread when the question has an answer.
Review Changes
Linear records edits so teammates see how a document evolves. Agree on one owner per document to avoid conflicting changes.
A Simple Requirements Template
Title: Invoice List 1. Problem What users cannot do today 2. Goal What users can do after release 3. Scope Included and excluded items 4. Design Link to mockups 5. Open Questions Items needing decisions 6. Tasks Links to Linear issues
Writing Habits That Help
- Start with the problem. Readers understand a solution only after they understand the need.
- Use short paragraphs and clear headings.
- Keep one source of truth. Update the document instead of copying text into many places.
- Archive outdated documents so searches return current information.
Organize a Growing Library
Libraries grow fast. Group documents by project and name them with clear titles. "Technical Design: Invoice List" tells readers more than "Design v2". Add the date to meeting notes so readers know which session the notes cover.
Assign Ownership
Name an owner for each important document. The owner keeps the content accurate and answers questions. Documents without owners decay quickly.
Review on a Schedule
Check core documents every quarter. Update facts, remove obsolete sections, and archive anything no longer useful. A short review prevents confusion later.
Search Across Documents
Use the command menu to search document titles and text. Good headings and plain keywords help teammates find answers in seconds.