Skip to main content
Automatically keep your work and documentation completely in sync.LearnaboutDocs.

Ultimate Setup Series: Best Practices for Docs

Erika Carter

Now, for the first time, a team's entire product development flow can be stitched together in one tool. That tool is us, Shortcut. How convenient.

Docs

Docs helps Shortcut users plan, manage, and document work for seamless, frustration-free software development.

In Shortcut, a Doc isn't your average ‘doc’, existing separately in another tool, like a Confluence or Notion. A Doc is part of the Shortcut fabric, and it's linked to Stories, Epics, Milestones, Labels, and more.

This means that teams can directly connect the planning side of work to the building side. And it's all done seamlessly in one unified user experience. Doesn’t that sound nice and easy?

This unified experience ensures there's only one version of the truth throughout the platform and it entirely eliminates dead documentation. Check out this video to learn the basics of Docs:

Get started with Docs

General Best Practices for Docs

Wondering what type of documentation is best for Docs, and what can be left to other documentation tools? Then it’s good that you made it to this section of this blog post, because we want to share some best practices to help guide you.

We recommend using Shortcut Docs for anything engineering, product, or project management related. Below are some use cases to get you started, but honestly any documentation you’re already using in your development process is a great use case for Docs.

The power of Docs is that it keeps everything in one place.

Docs for Product Managers

  • Product Requirement Docs (PRDs) 
  • Project kickoff
  • OKRs
  • MVP ideation

Docs for Engineers

  • Technical Design Doc (Architecture Requirement Docs (ARDs)
  • Architecture Decision Record (ADRs)
  • Incident Post Mortem
  • Squad Daily Stand Up

General Use Cases

  • 1:1s 
  • Meeting notes
  • Tutorials/process walk-throughs
  • Planning docs

Docs for Teams

  • Iteration Planning
  • Iteration Retrospective
  • Project Kickoff
  • Planning Docs

Check out the Dotlabs Demo Org to see example templates. If you like what you see, go ahead and copy and paste it into your own Doc and give it a whirl.

Not a Shortcut user yet? Start a free trial.

Now that we know what Docs is great for, you may be asking if there is anything you can’t do in Docs? And the answer is… no, no, not really. Docs is a general-purpose documentation tool that works for just about anything.

You may want to keep using your diagramming or drawing tools, but you can always link to those files directly from a Shortcut Doc.

Your entire company doesn’t necessarily have to move everything to Docs immediately, but we find that team members get huge value out of the integration with the rest of Shortcut and they are excited to dive in.

Best Practices for Organizing Docs

Linking Docs to Stories, Epics, Milestones, and Iterations

Shortcut makes it really easy to link Docs with Stories, Epics, Milestones, Iterations, and other Docs. When you want to find the PRD associated with an Epic, it’s linked to the Epic. When you want to find all the Stories associated with a PRD, they’re linked right in the Doc.

Shortcut Docs

Collections

A secondary way to organize your Docs is Collections. Collections are different from the traditional folder structure because they allow you to link Docs to multiple Collections.

For example, you might write, “Write a PRD about building a new Stories Backlog feature”. That PRD could be added to the “PRD” Collection as well as the “Backlog” Collection. This makes it easier to find, and Docs doesn’t bind you to a strict way of organizing.

Shortcut Docs

If you have any ideas on how you’d like to organize Docs within Shortcut, give us a shout on Discord! We are constantly evolving our feature set to better meet your organization’s needs.

Search, Following, and Recent

Following

Select the Star at the top of any Doc to add it to your Followed Docs. This is a great place to keep the Docs you actively work on and you want to stay up to date on.

Think of this as your personal folder or space to view the Docs you use the most. Following a Doc will add it to Following on the Doc menu and will send you an email notification when comments are made on the Doc.

Shortcut Docs

Recent Docs

This is a great place to quickly jump back into a Doc you were recently working on. At a glance, it is easy to see the Doc Owner, the last time you viewed it, and more.

Search

If your organization has a lot of Docs, search might be the fastest way to find the Doc you’re looking for.

Best Practices for Incorporating Docs into your Workflow

Add Docs to Story Templates

When creating or updating your Story templates it’s a great idea to link any Docs that will be needed. A common use case is to link a template Doc to the Story so users can duplicate the Doc and then link it to the Story.

Shortcut Docs

Use Epics and Milestones as your information hub. Connect Docs

Epics and Milestones are where you are planning your features and larger goals. Link key Docs to your Epics and Milestones to turn them into true hubs, where all the key information about a project can be found.

Shortcut Docs

Start building out Milestones, Epics, and Stories while Planning with Docs

Many teams like to collaborate and plan within a Doc. If you have a list of ideas to research, chores to do, or features to complete, just grab those sentences right from the doc and create the necessary stories.

If you have a topic with several sub-bullets, grab all the text and the topic will be your story title and all the sub-bullets will be in the story description. Magic!

Change management 

As with any change, there are things you can do to make the transition to Docs easier for your team. Here are some things we have seen work well:

  • Create a tool ecosystem
    undefinedundefined
  • Outline the use cases your team plans to use Docs for
    undefinedundefined
  • Create a Collection of “Templates”
    undefinedundefinedundefined
Shortcut Docs
  • Transfer key Docs into Shortcut
    undefinedundefined
  • Share the Getting Started with Docs video so everyone is comfortable with how to get started

Quick Tips for Docs

Create a Story from a Doc

Highlight text and click Create Story. This keeps you working where you are and automatically links the Story in the Doc.

Link Docs to your Stories, Milestones, Epics, and Docs

Your Docs are always up to date and where you need them with the seamless linking of Docs in Shortcut.

You can link Stories, Epics, Milestones, Iterations, and Docs in your Doc.

You can also link Docs to your Stories, Milestones, Epics, and Iterations:

Shortcut Docs

Relationship Panel

The Docs Relationship panel allows you to view all the Doc relationships. This allows you to see what is mentioned in the Doc and where the Doc has been linked (Story, Epic, Milestone, or Iteration at a glance.

Shortcut Docs

Tips for using Tables

Tables are one of the most used features in Docs. Here are some tips to get the most out of them.

  • Add a Header: Toggle on header row to shade the top row and bold the text, making a clear header row with one click.
  • Additional Formatting: Use Table Properties and Cell Properties to adjust background color, dimensions, and text alignment. 
  • Add an image: To add an image, click into the cell and select the Add/Edit plus to insert image or media. You can also copy and paste an image into a cell.
  • Insert paragraph: To add a line above or below a table hover and select the arrow. 
  • Create a Story: Highlight text and select Create Story to create and link a Story directly from a table
  • Link Stories, Epics, and Doc: Type forward slash and then search and add a Story, Epics, or Doc to the table. 

Collaborate with mentions and comments

Pull key stakeholders into the conversation by @mentioning their names, which will send a notification. Use comments to add key callouts. To get notified on all comments added to a Doc (even when you aren’t mentioned) Follow a Doc by selecting the star.

Shortcut Docs

How working in Shortcut is different

We think the way teams create software today is fundamentally broken. Their work lives in a vast array of tools, spread out across dozens of Google Chrome tabs - it's a mess. Information and important context is lost as communications are done and decisions are made in silos within Slack, Google Docs, Confluence, JIRA, and other tools.

Everything feels disjointed, and moving between these tools requires intense context switching - wasting precious mental energy that should instead be focused on doing the actual work itself.

At Shortcut, we think there's a better way. And Docs is a big part of this - making a fully integrated hub for teams to plan, manage, and document their work all through one unified experience with zero context switching.

To learn more about how working in Shortcut is different, read the manifesto.

To learn more best practices, check out the Shortcut Training Hub.

But the best way to see how working in Shortcut is different than Jira, Trello, Linear, Asana, or any other project management tool, for that matter, is to sign up for your free trial. What are you waiting for?

More stories from Shortcut