Dashboard Help System – Implementation Guide

Purpose

This page explains how dashboard pages provide integrated user help.

Goal:

guide club members directly inside the system
explain what each dashboard is for
avoid separate manuals or PDFs
reduce mistakes during data entry

Help must be visible at the place where the user works.

Design principles

The help system follows these rules:

documentation is integrated, not external
each dashboard has its own explanation
help is easy to maintain
help does not clutter the screen
layout is identical on all dashboards

Technical approach:

one help subpage per dashboard
one reusable template
transclusion into dashboard page
collapsible display

Structure

For every dashboard:

Dashboard:Chapter
Dashboard:Chapter/Help

Dashboard:Place
Dashboard:Place/Help

Dashboard:Organisation
Dashboard:Organisation/Help

etc.

Each dashboard has its own help subpage.

Step 1 – Create the reusable template

Create:

Template:DashboardHelp

Content:

<includeonly>
<div class="mw-collapsible mw-collapsed"
     style="border:1px solid #ccc; padding:8px; margin-bottom:12px; background:#f8f9fa;">

'''ℹ️ Help – click to open'''

<div class="mw-collapsible-content">
{{{1}}}
</div>

</div>
</includeonly>

Purpose:

provides consistent styling
provides collapsible behaviour
keeps dashboards compact
avoids repeating HTML everywhere

Step 2 – Create a Help subpage

Example:

Dashboard:Chapter/Help

Typical content:

== Purpose ==
Use this page to manage historical chapters.

== When to use ==
Create a chapter when you define a new historical period or theme.

== Examples ==
* CH01 – Early History
* CH02 – Interwar Period

== Do NOT use for ==
* buildings
* persons
* organisations

Guidelines:

keep short
use examples
avoid technical language
focus on practical usage

Step 3 – Include help in the dashboard

At the top of the dashboard page:

{{DashboardHelp|{{/Help}}}}

Explanation:

Template:/Help loads the subpage
DashboardHelp wraps it in a collapsible box

Result:

User sees:

 ℹ️ Help – click to open

Click → explanation appears.

Why use subpages instead of writing help directly in the dashboard?

Advantages:

separation of concerns
easier editing
cleaner dashboard source
reusable template
successors immediately understand structure
documentation can be updated without touching logic

Why collapsible?

Dashboards often contain:

large tables
many records
frequent data entry

Permanent help text would push content down.

Collapsible:

visible when needed
hidden during work
better UX

Recommended writing style

Write for non-technical users.

Good:

short sentences
concrete examples
“do this / do not do this”

Avoid:

database terminology
technical explanations
long paragraphs

Example complete dashboard

Dashboard:Chapter

= Chapter Management =

{{DashboardHelp|{{/Help}}}}

{| class="wikitable sortable"
! Code !! Title !! Parent
{{#cargo_query:
 tables=Chapters
 |fields=_pageName,code,title,parent
 |format=template
 |template=ChapterRow
 |named args=yes
}}
|}

{{#forminput:
 form=Chapter
 |namespace=Chapter
 |button text=➕ New chapter
}}

Maintenance

When rules change:

1. edit only the /Help subpage 2. dashboards update automatically

No template changes required.

Conclusion

This system:

integrates documentation directly into the workflow
improves usability
reduces training effort
prevents data entry mistakes
keeps dashboards clean

This approach is recommended for all present and future dashboards.