Learn how to make your work on Terra understandable and reproducible - for yourself, your team, and others - with clear and complete documentation. Read on for best practice guidelines to help improve documentation in workspace dashboards and in notebooks.
Workspace dashboard documentation best practices
Why good documentation matters
Your Workspace Dashboard should include - or clearly reference - any information needed to reproduce the analysis. This makes it easier for your colleagues and even yourself (e.g., if you return to the workspace after some time).
How to add documentation to your workspace dashboard
Workspace documentation is written in GitHub-flavored Markdown, with a handful of exceptions (for example, the emoji shortcut and linking by id within the page are not currently allowed in Terra). You can edit the dashboard by clicking the pencil icon to the right of the About the workspace heading at the top of the Dashboard tab.
Must-have Dashboard components
Don't want to start from scratch? Use our template! Click here for a template dashboard.
At a minimum, tutorial and template Workspace Dashboards should include the components below, set apart with h1 or h2 headings in Markdown (i.e., #
or ##
).
1. Overview paragraph
The first paragraph should include a short, descriptive summary. The first paragraph (or the first five lines of a long paragraph) will be displayed on the workspace preview card with no Markdown.
Do not include graphics, lists of author names, or other information before the overview paragraph, or else it will be more difficult for browsing users to assess whether the workspace is useful for their work.
2. Workspace purpose (i.e.,"What am I going to be doing?")
This should be brief and at the top (could be part of the overview).
3. Workspace expectations
Answer the following questions:
- How much will it cost?
- How long will it take?
- What tools will be used?
- What is the expected outcome?
Include these questions as section headers, using the #
or ##
syntax in Markdown.
4. Separate step-by-step instructions
Your work may require users to follow a detailed set of instructions, but dashboards that include step-by-step instructions (with screenshots) can be overwhelming. Instead of making readers scroll through endless instructions, write separate instructions (in PDF or external online format such as GitBook or Zendesk) and include links to those separate instructions in the dashboard.
For examples of how to structure separate step-by-step instructions, see Workflows Quickstart Part 1 or a pdf version of the same instructions.
Make sure to follow Markdown best practicesTo make sure your Dashboard--as well as the Workspace preview card in Your Workspaces or Featured Workspaces pages--renders correctly, see the Markdown Best Practices.
Heading Best Practices
Markdown applications don’t agree on how to handle a missing space between the number signs (#) and the heading name. For compatibility, always put a space between the number signs and the heading name.
Paragraph Best Practices
To create paragraphs, use a blank line to separate one or more lines of text. You can use two or more spaces (commonly referred to as “trailing whitespace”) for line breaks in nearly every Markdown application, but it’s controversial. It’s hard to see trailing whitespace in an editor, and many people put two spaces after every sentence. For this reason, you may want to use something other than trailing whitespace for line breaks. If your Markdown application supports HTML, you can use the <br> HTML tag.
For compatibility, use trailing white space or the <br> HTML tag at the end of the line. Unless the paragraph is in a list, don’t indent paragraphs with spaces or tabs.
Overall dashboard recommendations
Dashboards have somewhat limited formatting options, since security considerations require a version of Markdown that doesn't support Cascading Style Sheets (CSS) or anchor tags (which are useful for making a table of contents). To capture the information you want while making it easier for people to quickly find what they need, take advantage of these suggestions.
1. Limit dashboards to high-level content
Keep dashboard documentation to a minimum. A clear dashboard with adequate space in between headers and grouping of relevant blocks is a more effective way to communicate study goals and methods than a dashboard that includes all of the information you might include a paper's methods section. Use links to reference more information, when needed.
2. Use whitespace (not horizontal lines) to group information in sections
Markdown puts the same amount of space between every item, which means a lot of scrolling without a lot of breaks. It's tempting to use horizontal lines ("-------" in Markdown) to break the text up; but in practice, these make for a cluttered dashboard that is hard to read.
Note the additional whitespace before each section header in the screenshot below.
Use the following code to add whitespace to any part of your dashboard: <br><br>
3. Use visuals
Graphic elements can help visual learners and break up a long dashboard description.
Example code to add visuals
There are two ways to add an image to your dashboard: with Markdown or with HTML.
-
To add an image with Markdown, open the dashboard edit menu and place your cursor at the position where you want the image to appear. Then, click the picture icon in the dashboard edit menu. Once you click the icon, Terra will add the following line to your dashboard's markdown:

Replace the text within the brackets with the image title, and replace the text within the parentheses with its the location. The image must be stored online (in a public Google bucket, for example) for it to be viewable.
Note: If you are embedding images using Markdown (instead of HTML, below) you may need to scale images to fit nicely in the dashboard, as Markdown puts the image in full size, whatever size that is.
-
To add an image using HTML, open your dashboard edit menu and add a line of code like the following example to the position where you want the image to appear:
<img alt="A Warm Hello!" title="Hello, World!" src="https://i.imgur.com/MdueLu9.gif" width="64">
Use HTML tags to make your dashboard more legible
To make your dashboard easier to read, you can also use some embedded HTML tags. Note that although custom scripting and styling (i.e., CSS code, and alt tags) are not allowed, most HTML is.
Here are a few examples showing how to use HTML in your dashboard. This is only a subset of what you can do with HTML tags! For a full list of the HTML allowed in GitHub Markdown (the kind used in Terra Dashboards), see their documentation.
Opening a link in a new browser tab
<a href="https://somewhere" target="_blank">link text</a>
Superscript and subscript
Hello<sup>1</sup><sub>2</sub>
Notebooks documentation Best Practices
Combining documentation and code, notebooks are a wonderful tool to make your analysis more understandable, shareable, and reproducible - for yourself, your colleagues, and others. To make the most of the documentation tools in a notebook, follow the Best Practices suggestions below.
1. Use collapsible headings to streamline information
Collapsible headings are exactly what they sound like: sub-section Markdown cells nested under a heading. To use collapsible headings, click on the downward-facing gray arrow at the left of the Markdown cell to collapse the sections under that heading. The saved Notebook will save these states.
You can use collapsible headings to hide optional information:
Collapsed tip
Expanded tip
Be careful when collapsing sections that include code cellsIf you collapse a section that includes code cells, the code cells will be hidden and will not run until you expand the section. For this reason, you may need to be careful when nesting your sections to make sure the code isn't collapsed.
Here's an example: This collapsed section includes code that won't run unless you first expand the section.
Note: The section automatically expands if you run the top Markdown cell (the one in the screenshot above). This means that if you use the "Run all" commands, the hidden cells will run:
2. Include a documentation reference key
Format consistently and include a reference key to help users navigate your notebook. Using consistent formatting for code, additional information, tips, etc. will help your notebooks work well together, and make it easier to maintain good documentation across all work.
Example documentation reference key
3. Document with code cell comments
It's best practice to include comments directly in code cells (use "# comment here
" formatting) written in plain language to describe what the code in the cell does.
4. Use codefolding to hide long code blocks
Not everyone running your notebook will need to know the coding details of each cell. But a beautiful thing about a well-documented notebook is that anyone can go through the analysis and understand the results without having to know how to program. To focus on results without getting bogged down in coding details, use codefolding to hide the full commands. People who want to know the exact syntax can easily unfold the code.
To use codefolding, click on the downward-facing gray arrow at the left of the code cell to fold the code. Saving the notebook will save the state of your folded cells.
Folded version
Unfolded version
Best practices example
For an example of a workspace that follows these Best Practices (in notebooks as well as in dashboard documentation!), check out the Intro to Terra (Azure ) Quickstart.