Topic descriptions
Last updated
Last updated
At the center of every topic's page is a real-time, collaborative document. It's the best place to capture the context that people working on the topic will need, both for now and for the future. Things like:
An overview of what needs to be done
Why the work is being done in the first place
Links to resources in other systems
Topic descriptions are entirely optional. After all, sometimes a topic's context is completely clear just from the title!
When you do decide to write a description, you can draft it entirely on your own, or you can collaborate live with your team.
Here are some scenarios where editing in real-time with teammates is helpful:
Capturing meeting notes: Everyone in a meeting can view the topic and watch in real time as the notetaker captures the notes. They can even make corrections themselves.
Cross-functional collaboration: A cross-functional team can collaboratively edit a topic’s description to hammer out a shared understanding of the work to be done from each of their perspectives.
Retrospectives: Using a Flat topic’s description to capture a project’s retrospective is a great way to add to your team’s knowledge base. With collaborative, real-time editing, your team can hash out the retrospective in a joint “jam session”.
A topic's description is a fully collaborative, real-time document right out-of-the-box. To edit a topic’s description, just start typing. Multiple users on your team can view and edit a topic's description at the same time, and everyone's edits are synchronized and merged automatically.
To access the formatting toolbar, click into the topic's description, then click the formatting icon that appears in the upper right corner of the document.
The editor recognizes all of the common formatting keyboard shortcuts you'd expect:
Ctrl/Cmd B to toggle bold
Ctrl/Cmd I to toggle italics
Ctrl/Cmd Shift X to toggle strikethrough
Ctrl/Cmd E to toggle monospace text / code
Tab while in a list item to indent, and Shift Tab while in a list item to dedent
Ctrl/Cmd K to insert a link or make selected text a link
Ctrl/Cmd Z to undo and Ctrl/Cmd Shift Z to redo
The editor recognizes basic Markdown syntax formatting:
**text** for bold text
*text* or _text_ for italic text
~text~ or ~~text~~ for strikethrough text
`text` for monospace text / code
# , ## , ### , #### , ##### , or ###### at the beginning of a line for headings at different levels
> at the beginning of a line for a block quote
- or * at the beginning of a line for a bulleted list
1. at the beginning of a line for a numbered list
--- at the beginning of a line for a horizontal divider
``` at the beginning of a line, then Enter, for a code block
You can insert emojis by typing : followed by the emoji's name or alias, such as :+1: or :thumbsup: for 👍. Or type : and a portion of the emoji's name, then select the emoji you want from the dropdown picker.
To add an image, click the image icon in the toolbar or just drag and drop an image from your computer into the editor area.
You can reference another topic by typing # followed by the topic's ID. Or type # and a portion of the topic's ID, title, labels, etc., then select the topic from the dropdown picker.
