All Collections
Business Intelligence Courses
Course Development
Style guidelines for BI courses
Style guidelines for BI courses

For BI SMEs: Learn the style guidelines, which helps keeps our BI courses clean and consistent across the platform.

Maarten Van den Broeck avatar
Written by Maarten Van den Broeck
Updated over a week ago

BI courses require their own set of style guidelines than the ones that have been established for traditional coding courses. This is because the UI interface, field names, BI tool terminology need to be described in a clear and consistent style. Make sure to adhere to the following when creating content for BI tools like Tableau and Power BI:

Use italics for BI tool terminology

The BI tool terminology should be capitalized and italicized. Anything that can be clicked on or dragged within the BI tool UI must be in italics. This includes anything that is in a drop-down menu or a popup window. In more detail, this is true for both the conceptual terms, e.g., Calculated Fields, and the UI items, e.g., Marks card, Analysis tab, Data pane, and Show Me button.

In addition to the above, if hovering over elements within the UI shows additional text, then this should also be in italics if it is referenced in the course material.

Finally, when using italic formatting, ensure context is applied - specifically action-based context. If the instructions or hints are action-based, then italics should be used. This means that italics will be used more regularly in the hints of exercises.

Good: Drag Usertype to Color in the Marks card.

Bad: Drag Usertype to color in the marks card.

Good: In the dropdown at the top of the Marks card, select Bar.

Bad: In the dropdown at the top of the Marks Card, select “Bar”.

Use American English

We are an American company, and the USA contains our largest group of students, so all courses/projects must be written in American English. It is up to you to ensure this.

Good: This standardizes the modeling of colors.

Bad: This standardises the modelling of colours.

Use full sentences

Students are going to read the contents of your course/project; you need to make sure to use full, properly punctuated, clear sentences. Remember that you will not be there to explain things to students, so listing things you think students will understand is not going to be enough.

When using any numbers from ten and under, you should use text to write out the number. However, if you are using any number ten and under in a sentence that is related to inputting a value within the BI tool, then you should use numerical digits, along with code formatting (see the following section).

Good: We have five active and five inactive relationships.

Bad: We have 5 active and 5 inactive relationships.

Use code formatting

Inline code formatting should be used for the following elements:

  • Field names*

  • File names

  • Table names*

  • Sheet, dashboard, and stories names*

  • DAX code (see DAX code section below)

  • Input numbers in a hint or instruction, e.g., "Change the decimal places entry to 3".

When asking learners to enter the name of a field, table, sheet, dashboard, or story for the first time, do not use code formatting. Instead, use double quotes. In this instance, you are asking the learner to type something for the first time, and so double quotes are required. After this, any time a reference is made then you can use code formatting.

Field Names

Good: Add ScenarioName to the card visual in the top right corner of the report.

Bad: Add ScenarioName to the card visual in the top right corner of the report.

File Names

Good: Import the purchases.csv using the native Power BI method.

Bad: Import the purchases.csv using the native Power BI method.

Table Names

Good: Edit the query of DimCustomer to open up the Power Query Editor.

Bad: Edit the query of DimCustomer to open up the Power Query Editor.

Creating new sheet

Good: For this exercise, create a new page in the report called "Attrition".

Bad: For this exercise, create a new page in the report called Attrition.

Referring to a sheet

Good: For this exercise, create a new page in the report called Attrition.

Bad: For this exercise, create a new page in the report called "Attrition".

Input Numbers

Good: Change the size of the bar chart title to 25.

Bad: Change the size of the bar chart title to 25.

Use parentheses after function names

This formatting helps distinguish functions from variable names. Functions will be used when referring to DAX (in Power BI), as well as any cross-technology courses that will be using Python or R in a BI tool.

Good: Use the mean() function.

Bad: Use the mean function.

Use quotes for text input

When asking learners to input text and actually type something, then the input requested should be in quotes. Specifically for Power BI, chart titles or chart axes should also be referred to with quotes.

Good: Double-click on the y-axis and change the title to “New Bar Chart” in the dialogue box.

Bad: Double-click on the y-axis and change the title to New Bar Chart in the dialogue box.

Exercise file names

Names of workbooks (Tableau terminology, ending on .twbx) or reports (Power BI terminology, ending on .pbix) should follow this structure: n_m_keyword, where:

  • n is the chapter number

  • m is the exercise number (resets each chapter, always starting with n_1)

  • keyword is a lowercase keyword that makes it easier to identify the exercise. If there are multiple keywords, use snake_case, e.g. 3_1_inner_circle.twbx

Context

If this exercise builds on a workbook/report created in a previous exercise, the following sentence needs to be included at the bottom of the Context section using italics formatting:

If you lost progress, load the workbook 2_1_data_prep.twbx from the Workbooks folder on the Desktop.

Replace 2_1_data_prep.twbx with the exercise filename that contains the exercise's starting state.

Instructions

All instructions should have ending punctuation. Even if the last word is formatted as inline code. If there’s only one instruction in a single step, you don’t need to use bullet points. If there are multiple instructions in a step, you have to use bullet points.

Hints

Hints should always have ending punctuation unless the hint is a code snippet. If there’s only one hint in a single step, you don’t need to use bullet points. If there are multiple hints in a step, you have to use bullet points.

Because students don't have access to a solution, they should describe the steps to take from beginning to end to complete the exercise.

Scripts

With regards to scripts, additional formatting should be kept to a minimum. It is not necessary to put words/sentences in quotes or other such formats. The best practice is to write out sentences in full and avoid using abbreviations and numbering. Some examples of what to avoid include:

  • E.g.

  • I.e.

  • A) B) C)

  • 1) 2) 3)

When writing anything out that includes a period/full stop, it is necessary to write “dot” instead of just “.” so that the sentence is not broken up into smaller sentences by the caption creator. This includes the following items:

  • Website addresses

  • Functions, particularly when implementing any Python or R into BI course material

Alternative text

Alternative text should always be in full sentences and punctuated properly. The aim is to get as much information as possible into a sentence to clearly describe an image for the learner.

Calculated Fields (Tableau only)

The general rule is to put all calculated field syntax in code formatting (between backticks) in all exercise types, including the slides.

Note that Tableau doesn't use "=" signs, so don't use them in your formulas:

Good:

Bad:

You can use ":" or "=", as long as they are not code formatted (since they are not part of the formula).

As you've also noticed, use "____" (four underscores) as code scaffolding for blanks in intermediate hints for learners to fill out. Adjust the amount of code scaffolding (if any) based on the exercise's difficulty.

Note that the final hint should contain the full code of the calculated field.

DAX code (Power BI only)

The general rule is to put all DAX syntax in code formatting (between backticks) in all exercise types, including the slides.

Below is an example of how DAX code used in a hint in the DAX in Power BI course.

  • All functions should be followed by a ().

  • TRUE or FALSE should be put in code formatting if it is referring to code output. For example:

  • Add ____ (four underscores) as code scaffolding for blanks in intermediate hints and exercise files for learners to fill out. Adjust the amount of code scaffolding (if any) in the exercise file based on the exercise's difficulty. For example:

  • Hints of multistep exercises should help the learner but not give away the full answer. You can use the hint of the final step to give the exact syntax. For example:

Hint in step 2:

Hint in the final step with the exercise question:


Did this answer your question?