.svg)
Ultimate Setup Series: Best Practices for Docs
Welcome to Shortcut! Shortcut is project management without all the management, built by our software team for your software team. We help you plan, collaborate, build, and measure success. Speaking of success, we want to make sure that you’re set up for... wait for it…
Wait for it a little bit more…
Wait one more second...
Success.
That’s why we’ve created this Ultimate Setup Series. This is the fourth post in this series. Read the last post here, which is about best practices for Docs. In this post, we’ll talk about best practices for creating and prioritizing your backlog of work in Shortcut.
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:
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
Docs for Engineers
- Technical Design Doc
- Architecture Decision Record (ADRs)
- Incident Post Mortem
- Squad Daily Standups
- Iteration Planning
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.
Organize with Collections, Sub-collections, and Favorite Docs
A secondary way to organize your Docs is Collections. Collections differ from the traditional folder structure because they allow you to link Docs to multiple Collections. Use the more menu to keep your Collections in order by adding a Sub-Collection and view all Docs in a Collection by viewing the Collection Page. Learn more at the Training Hub.
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.
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.
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.
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.
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
- 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:
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.
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.
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?
