View source for ICT:Dashboard help function

= 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:

<pre>
<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>
</pre>

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:

<pre>
== 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
</pre>

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:

<pre>
{{DashboardHelp|{{/Help}}}}
</pre>

Explanation:

* {{/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

<pre>
= 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
}}
</pre>


== 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.