Documentation best practices (dashboards and notebooks)

Allie Cliffe
  • Updated

In this article, you'll 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

Workspace documentation is written in GitHub-flavored Markdown, with a handful of exceptions (currently, the emoji shortcut and linking by id within the page are not allowed in Terra). You can edit the dashboard by clicking the pencil icon at the top of the Dashboard tab. 

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). 

Must-have Dashboard components

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 in the workspace card with no Markdown. 

Featured-workspace_dashboard-card-example.png

Do not include graphics, lists of author names, or other information before the intro paragraph. 

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

  • How much will it cost?
  • How long will it take?
  • What tools will I be using?
  • What is the expected outcome?

(include as sections - i.e., #, ## in Markdown)

4. Separate step-by-step instructions

Your work may require unfamiliar users to follow a detailed set of instructions, but dashboards that include step-by-step instructions (with screenshots) can be hard to process. 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.

Example of separate step-by-step instructions (Zendesk article or pdf)

Overall dashboard recommendations

Dashboards have somewhat limited formatting options, since security considerations require a version of Markdown that doesn't support CSS or anchor tags (e.g., 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 dashboard to high-level content

Keep dashboard documentation to a minimum by focusing on high-level information. 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. Use links to reference more information, when needed. 

Click here for an example dashboard.

Example dashboard screenshot

Notebooks-QuickStart-dashboard_Screen_Shot.png

2. Offload details like step-by-step instructions or configurations

For step-by-step instructions, link to a support (for User-Ed/Comms) or GitBook article, or a PDF. For an example of step-by-step instructions to go along with a workspace, see this support article or this PDF example of step-by-step instructions for the Workflows QuickStart. Don't forget to make it very clear in the dashboard how to access these resources!

Example of separate step-by-step instructions (Zendesk article or pdf)

3. 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. Additionally, horizontal lines ("-------" in Markdown) make for a cluttered dashboard that is hard to read.

To add whitespace, insert a fake graphic piece (note you may have to play with the size of the whitespace to get it right).  

Example whitespace in dashboard

A screenshot of one section of the Quickstart dashboard is below. Note the additional whitespace before each section header.
S50b_Best_Practices_Dashboard_Documentation.png

Example Markdown code to add whitespace

 ![white space](href="https://storage.cloud.google.com/terra-featured-workspaces/white-space.jpg")

4. Use visuals

Graphic elements can help visual learners, and break up a long dashboard description. You can use the graphic assets here to generate your own. Note: if you are embedding images using Markdown (instead of HTML, below) you will likely need to scale images to fit nicely in the dashboard, as Markdown puts the image in full size, whatever size that is.

Example visual (workspace flow diagram)

Notebooks_QuickStart_flow.png

Example code to add visuals

To add an image, click the picture icon in the dashboard edit menu. The image must be stored online (as in a public Google bucket) for it to be viewable. Once you click the icon, it will display the following:

 ![your-image-title - i.e. the "alt" tag](https://your-image-full-file-name) 

Within the brackets, put the image title, and in the parentheses, put the location.

Or use HTML (see more on this below):

<img alt="A Warm Hello!" title="Hello, World!" src="https://i.imgur.com/MdueLu9.gif" width="64">

Supported HTML tags in dashboard documentation

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.

Some HTML in Terra Dashboard examples

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.

Embedding an image

<img alt="A Warm Hello!" title="Hello, World!" src="https://i.imgur.com/MdueLu9.gif" width="64">: 
A Warm Hello!

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. 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. For example, see the screenshots by expanding the collapsed section below:

Collapsed tip

S50e_Collapsible_heading_tip.png

Expanded tip

S50f_Collapsible_heading_expanded_tip.png

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.

Check the following example:

This collapsed section includes code that won't run unless you first expand the section.

S50d_Collapsed_heading_example.png

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:
S50d_Collapsed_heading_example2.png

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 make your notebooks work well together, and make it easier to maintain good documentation across all work.

Example documentation reference key

S50g_Best_practices_documentation_key.png

3. Document with code cell comments

Best Practices is to include comments directly in the code cell (use "# comment here" formatting) written in plain language to describe what the code in the cell does.

Example code comments

S50h_Code_cell_comments.png

4. Use codefolding to hide long code blocks

Not everyone running your notebook will need to know the coding details of each cell. What's a beautiful thing about a well-documented notebook? 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

S50j_Code_cell_with_comments_folded.png

Unfolded version

S50h_Code_cell_comments.png

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 Terra-Notebooks-QuickStart.

 

G0-smiley-icon.png Congratulations! You've completed the article on documentation best practices (dashboards and notebooks)!

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.