If your goal is to make your work reproducible - for yourself, your team, and others - clear and complete documentation is critical. Documentation can make your analysis easy to understand and replicate, enabling you to reach and influence more people. Below are Best Practice Guidelines - developed by the UX and User Ed teams - to help improve documentation in Terra.

Contents

Workspace Dashboards Documentation Best Practices 
    - Must-have dashboard components
    - Overall dashboard recommendations

Notebooks documentation Best Practices Overview
   - Use collapsible headings to streamline information
   - Include a reference key
   - Document with code cell comments 
   - Use codefolding to hide long code blocks

Workspace Dashboards documentation best practices

At a minimum, tutorial and template workspace dashboards should include the following components. Scroll down for overall recommendations. 

Must-have dashboard components

1. Workspace purpose (i.e. "What am I going to be doing?")

This should be brief and at the top. Remember, the first sentence or two in the workspace dashboard is what will display on the workspace card in the Showcase section of the library.

2. Workspace expectations

Include well-identified sections such as How much will it cost? How long will it take? What tools will I be using? What is the expected outcome?

3. Separate step-by-step instructions

Instead of making readers scroll through an endless dashboard of instructions, write separate instructions and Include links (to a pdf or Zendesk article) in the dashboard.

Overall dashboard recommendations

For security reasons, Terra dashboards use a version of markdown that doesn't support html code. Because of this, dashboards have limited formatting options. To capture the information you want while making it easier for people to quickly find what they need to know, use these suggestions.  

1. Less is more

Keep dashboard documentation to a minimum by focusing on high-level information. A clean and clear dashboard, with adequate space in between headers and grouping of relevant blocks, is a clearer, more effective way to communicate the goals and methods of your woakspace.

2. Offload details

For step-by-step instructions, link to a Zendesk article (for User-Ed/Comms) or a PDF. For an example of step-by-step instructions to go along with a workspace, see this Zendesk article or this PDF example of step-by-step instructions for the Workflows-QuickStart. Make it clear how to access these resources.

3. Use whitespace to group relevant information together in sections 

Markdown puts the same amount of space between every item, which means a lot of scrolling. To separate sections, use white space, not lines ("-------" in markdown). The lines make for a cluttered dashboard that is hard to read. To use white spaces, insert a fake graphic piece (note you may have to play with the size of the whitespace to get it right):
)

4. Use visuals 

Graphics can help visual learners, and break up a long dashboard description. You can use the graphic assets here to generate your own, similar to the example below. 

Best practices dashboard example

For an example of a dashboard that uses all of these elements, see the Terra-Workflows-QuickStart. 

Notebooks documentation Best Practices

With a combination of documentation and code, Notebooks are a wonderful tool for making your analysis more understandable and reproducible - for yourself and your colleagues, as well as 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 sounds like: sub-section markdown cells nested under a heading will be collapsed.

You can use this to hide optional information, for example, see the screenshots by expanding the collapsed section below:

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. 

Warning: If 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 in order to make sure the code isn't collapsed. 

2. Include a documentation reference key

It is useful to use consistent formatting and include a reference key to help users navigate your notebook. Using a consistent formatting for code, additional information, tips, etc. will make your notebooks work well together, and will make it easier to maintain good documentation across all work. 

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: 

4. Use codefolding to hide long code blocks

Not everyone running your notebook will need to know the coding details of each cell. One beautiful thing about a well-documented notebook is being able to go through the analysis and understand the results without having to know how to program. To focus on the results and not get bogged down in the coding details, you can use codefolding to hide the full commands.  People who want to know the exact syntax can easily unfold the code. See the folded version of the code cell from the screenshot above:

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.   

Best practices example

For an example of a workspace that follows these Best Practices (including in notebooks as well as dashboard documentation!), check out the Terra-Notebooks-QuickStart.