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:
Context style guidelines
Instructions style guidelines
Hints style guidelines
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.
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 last section of this article for more details
Input numbers in a hint or instruction, e.g. "Change the decimal places entry to
3".
Good: Add Usertype to the sheet.
Bad: Add Usertype to the sheet.
Use parentheses after function names
This formatting helps distinguish functions from variable names.
Good: Use the mean() function.
Bad: Use the mean function.
Use italics for BI tool terminology
The BI tool terminology should be capitalized and italicized. This is true for both the conceptual terms, e.g., Dimensions, Measures, Calculated Fields, and the UI items, e.g., Marks card, Analysis tab, Data pane, Show Me button.
Good: Drag Usertype to Color in the Marks Card.
Bad: Drag Usertype to color in the marks card.
Use quotes for menu/dropdown items and charts
The items that can be found when opening a menu or that are listed in a dropdown list should use quotes.
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.
Good: Double click on the y-axis and change the "Title" in the dialogue box.
Bad: Double click on the y-axis and change the Title in the dialogue box.
Specifically for Power BI, chart titles or chart axes should also be referred to with quotes.
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. 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.
DAX code
The general rule is to put all DAX syntax in code formatting (between backticks) in all exercise types.
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
().
TRUEorFALSEshould be put in code formatting if it is referring to code output. For example:
Add ____ (4 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: