Report style guide

Follow these guidelines for successful creation of NAM reports.

Before you begin

Before you invest your time in creating a report, be sure to examine the existing reports.

  • Could one of our explorers do the job for you as is? Check the Explore menu and other standard reports on the NAM Console.
  • Should we add something to the standard reports? If so, let us know.

Planning

If you are sure you want to create a report, you should plan the report to fit into the existing report scheme and maximize user experience.

  • Use "Sentence case" (first word capitalized), not "Title Case" (most words capitalized) for names and labels
  • Use breadcrumbs breadcrumbs
  • Use the standard color scheme
  • Consider extending the smart search functionality with questions that will be answered by your new report

When adding links to other reports, indicate where the link target is opening:

  • We use the down arrow at the beginning of a link title to indicate a link to the same report (reloading the current report in the same browser window but filtered to have a different focus).
  • We use the up arrow  at the end of a link title to indicate a link from this report to a different report in a different browser window.

When you create your own reports, we recommend that you do the same to maintain consistency.

Also, give your link an action name: say what the link will do, not where the link will go. For example, instead of User explore, name your link Analyze user activity to suggest the activity, not simply the name of the target.

And remember to use sentence case. In the example, it's "Analyze user activity" (not "Analyze User Activity"). This makes it easier to read and conforms to industry standards.

Linking to a new window

Open your link in a new window if it points to a report with different breadcrumbs.

To create a link that opens a new window from your report:

  • Add the "↗" arrow character to the end of the label
  • Set isNewWindowLink="true"

Example:

This is a link the "Slow operations" report.

<link target="Slow operations" name="Analyze slow operation cause breakdown ↗" isNewWindowLink="true">

Where:

  • The link label is a string that ends in " " to tell the user that the link will open in a new window.
  • The isNewWindowLink property is set to true to tell DMI to open the link in a new window.

Linking to the same window (to filter your report)

Open your link in the same window to filter your report.

To create a link from your report and to your report:

  • Add the " " arrow character to the beginning of the label
  • Set type="SELF"

Example:

This link opens the "User explorer" report as a SELF link (same window).

<link target="User explorer" name="⇲ Analyze user activity" type="SELF">

Where

  • The link label is a string that ends in "" to tell the user that the link will open the same report in the same window (presumably with a filter).
  • The link type is set to SELF to tell DMI to open the link in the same window.
    Never open SELF-links in a new window.

Filters

  • Never set filters as Hidden + Read-write
  • Avoid Hidden + Read only
  • Try to keep all filters as Report header + Read write (Read only or Fixed in special cases) or Hidden + Fixed
  • Use Section header only when particular section may have different filter value than the rest of the report.
    Example: “Conversation details” perspective in Network explorer report

Apply filter actions in general

  • Customize action label: explain what will happen
  • Avoid passing filter to the same type of sections, e.g., other time charts; pass selection (select_*) instead
  • In some cases apply filter actions might need to be replaced with self-links selecting only single dimension

Applying time filter

  • Avoid passing time to other charts

  • Apply “Time selection” to other charts

  • Set time range visibility on affected sections to Report header and Read only

Sections

Section list

  • Use to change content of a section, not the whole report
  • Use the same section name for all sections bound together
  • Try to make it read as a statement
  • Never use to leave the report or open in new window

Section buttons

  • Only available in: Table, UD, Annotation, Chart, Location status;

  • Use to indicate actions that will:

    • switch context to another report/dashboard,
    • invoke action on the whole section,
  • In most cases they should open destination report in a new window.

Report tabs

  • Tabs switch context but they should stay the same across reports bound together
  • Use the same report title for multiple reports bound together
  • Never use to open different “dashboard” or open in new window

Report annotations

  • Provide auxiliary information, with additional links to other reports, changing the context of analysis with currently applied filters
  • Since it is folded by default - report annotations and links should be considered “additional” or “advanced”, while primary descriptions and links should be delivered with section annotations and section buttons.
  • Tell users where they are - not how they got here
  • Enable users to back-track along recommended workflow path
  • Use coloring scheme to help users understand the purpose and context
  • Avoid self-links or ignore-links if you plan to inherit definitions.
  • Add last breadcrumb with link to the same report to enable to reset current report state, e.g., clear time selected at chart

Charts

  • Always show legend and Y-axis
  • In most cases put legend below
  • Minimal screen width is 1366, optimize charts auto-expand by providing maximal width, e.g., for 2 column layout each chart could be 600px (minimal width)

Time

  • Hide time range in custom time ranged charts.
  • Gather all section time ranges into header level, unless like in some explorers - charts control time selection but are not affected by that change, and only a handful of visible sections has time range changed - in that case those sections should show their time range at the section level.
  • Use last breadcrumb with “reset time at sections” and “clear time selection” to enable to bring back default time settings.

Enabling time selection on chart

  • Do not publish time to other time charts
  • Publish Time selection to other time charts
  • All non-fixed time sections should have RO time settings
  • Ensure last breadcrumb enables to remove Time selection and resets time at the section level:
    <link target="Operation explorer" name="Explore" type="SELF"> <dmiLink target="TIMERANGE" linkSrcType="VALUE" source="clear_section" /> <dmiLink target="select_begT" linkSrcType="CLEAR" /> </link>

Advanced topics

Report state with params section

If used to control section list and report tabs: use the VERY same definition of tabs in all states, i.e., control what is selected with expression, NOT with “true” applied in every section/report separately

Order of sections in XML

Initially sections are ordered according to order they were added to the report, regardless their actual location in grid

Tip: To avoid creating messy XML, be sure to re-order them as closely as possible when you have all sections in place.