How to add a README

A README is an essential part of every code repository. The better the README, the more collaborators will want to work on your code. The same holds true for your data assets.

Each data asset should have its own README, which provides a description of its characteristics and other critical information. Atlan allows users to add a README for every data asset, using an intuitive, rich text editor.

You can document the tribal knowledge associated with each data asset in a README and reduce dependencies on your team members. The README appears right below each data table in the asset profile, displaying the data and the metadata on the same page and bridging the gap between the two.

Atlan currently supports the following file types for asset READMEs:

  • Google Docs
  • Google Sheets
  • Google Slides
  • Miro boards
  • FigJam boards
  • Lucidchart
  • dbdiagram
  • ERD Lab
  • Microsoft Word
  • Microsoft Excel
  • Microsoft PowerPoint
  • Google Data Studio
  • Google Looker Studio
  • Canva


A README can be added to different types of data assets in Atlan, including BI dashboards, widgets, columns, databases, and schemas.

The character limit for READMEs is 100,000 characters. A portion of this limit is used to ensure compatibility with rich text formatting, slightly reducing the available character limit.


To add a README to an asset, follow these steps:

  1. On the Atlan homepage, click Assets in the left menu.
  2. Click on an asset to view its asset profile.
  3. In the Readme section of the asset profile, click +Add.
  4. You can either:
    • Click Blank Page to create a new README from scratch.
    • Click Use to select an existing template as a starting point.
  5. Enter your knowledge into the README. Type / to use the text editor options to format your text, embed links, and more:
    • Click Heading 1 to add a title or main heading.
    • Click Heading 2 to add subheadings and create sections.
    • Click Heading 3 to create subcategories within sections.
    • Click Bulleted List to create a bulleted list.
    • Click Numbered List to create an ordered list.
    • Click Checklist to create a checklist of items.
    • Click Formula to add formulae from a list of supported functions.
    • Click Code to add a code snippet.
    • Click Image to embed or upload an image.
    • Click Quote to add block quotations.
    • Click Mention to tag another user in your Atlan workspace.
    • Click Table to create a table.
    • Click Google Docs to paste a Google Doc link and embed your online documents.
    • Click Google Sheets to paste a Google Sheets link and embed your online spreadsheets.
    • Click Google Slides to paste a Google Slides link and embed your online presentations.
    • Click Miro Board to paste a Miro board link and embed your boards.
    • Click FigJam to paste a FigJam link and embed your boards.
    • Click Lucidchart to paste a Lucidchart link and embed your documents or models.
      🚨 Careful! To embed a Lucidchart document or model, you will need to activate the embed code. Activating an embed code will disable password protection on published documents and make them accessible publicly.
    • Click DBDiagram to paste a dbdiagram link and embed your database diagrams.
    • Click ERD Lab to paste an ERD Lab link and embed your entity relationship diagrams.
    • Click Microsoft Word to paste a Microsoft Word link and embed your online documents.
    • Click Microsoft Excel to paste a Microsoft Excel link and embed your online spreadsheets.
    • Click Microsoft PowerPoint to paste a Microsoft PowerPoint link and embed your online presentations.
    • Click Google Data Studio or Google Looker Studio to paste a Google Data Studio or Google Looker Studio link and embed your reports and dashboards.
    • Click Canva to paste a Canva link and embed your Canva graphics and presentations.
  6. Click Save.

Your README is ready to be shared! πŸŽ‰

Although it may take some time to create, a README is a critical step for documenting any data asset and making it trustworthy.

Use README shortcuts

Atlan supports keyboard and markdown shortcuts to supercharge your README documentation.

Keyboard shortcuts

In the table below, Mod stands for modifier key β€” Command for Mac and Ctrl for Windows.

Shortcut Action
Mod + Shift + B block quote
Mod + B bold
Mod + I italics
Mod + Shift + 8 bulleted list
Mod + E code
Mod + Alt + C code block
Enter thrice, βŒ„ exit code block
Mod + Alt + 1 heading 1
Mod + Alt + 2 heading 2
Mod + Alt + 3 heading 3
Mod + Alt + 4 heading 4
Mod + Alt + 5 heading 5
Mod + Alt + 1 heading 6
Enter add new list item
Shift + Tab uplift list item
Tab sink list item
Mod + Shift + 7 ordered list
Mod + Alt + 0 set paragraph
Mod + Shift + X strikethrough
Mod + U underline
Mod + Shift + 9 toggle task list
Mod + Shift + L left align text
Mod + Shift + E center align text
Mod + Shift + R right align text
Mod + Shift + J justify text
Mod + Shift + H highlight text
Within a table:  
Tab go to next cell
Shift + Tab go to previous cell
Backspace delete table when all cells are selected
Mod - Backspace delete table when all cells are selected
Delete delete table when all cells are selected
Mod - Delete delete table when all cells are selected

Markdown shortcuts

Markdown shortcuts are triggered by pressing space after the shortcut β€” except for bold and italics. For example, to add a block quote, type > and then tap the spacebar.

Shortcut Action
> block quote
** (text) **, __ bold
* (text) *, _ italics
- bulleted list
` code
```, ~~~ code block
# heading 1
## heading 2
### heading 3
#### heading 4
##### heading 5
###### heading 6
---,--, ___ horizontal divider
any numeric digit ordered list
~~ strikethrough
[] unchecked task
[x] checked task
== highlight

Related articles

Was this article helpful?
2 out of 2 found this helpful