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
Scripts style guidelines
Alternative text style guidelines
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:
nis the chapter numbermis the exercise number (resets each chapter, always starting withn_1)keywordis 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.
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: