Bullet-proof UI Checklist (MediaWiki / Page Forms)

This page documents practical rules for designing robust, low-error user interfaces in MediaWiki using Page Forms and Cargo.

The target users of the system are historians and domain experts, not ICT specialists. The UI must therefore prevent mistakes by design, not by training.

This checklist is based on real production observations.

Core Principle

If a user can make a mistake, eventually someone will.

Therefore:

Do not rely on user understanding
Do not rely on documentation alone
Encode rules directly into the form UI whenever possible

1. Prefer Guidance over Enforcement (v1 rule)

In early versions (v1):

Guide users clearly
Avoid complex enforcement logic
Avoid JavaScript unless strictly necessary

Enforcement can be added later once behavior is understood.

2. Every Field Must Answer Three Questions

For each form field, the UI must make clear:

What should I do here?
What should I NOT do here?
What happens after I do it?

If the UI does not answer these visually or textually, the field is not safe.

3. Use Instructional Placeholders

Use placeholders to guide action and discourage typing when typing is not intended.

Example:

|placeholder=Click “Upload file” to select a file

Good use cases:

file uploads
auto-generated values
system-controlled fields

Placeholders are read before interaction and reduce errors.

4. Put Rules Next to the Field, Not in Documentation

Never rely on users reading separate documentation.

Rules must appear directly where the decision is made.

Example:

<small>
Exactly one file must be uploaded for each Asset.
The file name cannot be changed afterwards.
</small>

Short, explicit rules are preferred over long explanations.

5. Remove Wrong Affordances

Do not present UI elements that suggest the wrong action.

Examples:

Avoid text inputs where free typing is not expected
Prefer selectors, upload buttons, and controlled inputs

Do not “forbid” actions silently — avoid suggesting them visually.

6. Editable on Creation, Stable Afterwards

Many values should be decided once and then remain stable.

Use this pattern where applicable:

|editifempty=yes

Typical use cases:

identifiers
original file names
source references
archival metadata

This matches how archivists think: decide once, then preserve.

7. Avoid Ambiguous Optionality

Avoid wording like:

“optional”
“if applicable”
“you may leave empty”

Prefer explicit rules:

Bad:

(Optional – leave empty if using Organisation)

Better:

Use either Place or Organisation, not both.

Clear rules reduce hesitation and inconsistent data.

8. Separate Technical Identifiers from Human Labels

Page names are technical identifiers
Labels are human-readable and may change

Never expose technical identifiers unnecessarily in the UI. Always display labels where possible.

This prevents:

copying of technical IDs
accidental misuse
inconsistent conventions

9. No Silent Automation

If a value is generated automatically (now or in the future), announce this clearly in the UI.

Example:

<small>
This value is generated automatically by the system.
Do not try to change it manually.
</small>

Users must understand when the system is in control.

10. Prefer Deterministic Storage

For v1:

Prefer deterministic storage over strict typing
Avoid race conditions between UI and storage
Decouple user interaction from data persistence when necessary

Correctness is more important than elegance in early versions.

Final Sanity Check

Before accepting a form field, ask:

Can a user misunderstand this field?
Does the UI invite the wrong action?
Is the rule visible at the point of action?
Is the value stable when it should be?
Would a non-technical historian feel confident using this?

If any answer is “no”, improve the UI.

Status

This checklist is considered **stable for v1**. It will be extended when JavaScript-based enforcement and v2 automation are introduced.