Lessons Learned and Design Philosophy

This page documents the design philosophy and lessons learned that guide the development of this MediaWiki-based research system.

It exists to make implicit experience explicit, and to serve as a long-term guardrail against common project failure modes.

Background

Decades of experience in academic and government-related projects show a recurring pattern:

A significant portion of projects are never completed
Many completed systems are never used
Most successful systems only become useful after substantial rework

Despite advances in technology, this pattern has remained largely unchanged over time.

The primary causes are rarely technical. They are conceptual and organizational.

Core Observation

Most project failures originate from:

Unclear or unstable concepts
Implicit assumptions that are never documented
Premature implementation
Confusion between structure, storage, and presentation
Lack of a shared mental model among stakeholders

Once implementation begins, correcting these issues becomes exponentially more expensive.

Fundamental Principle

Implementation should follow understanding, not precede it.

This system is designed according to that principle.

Design Philosophy

The following principles guide all design and implementation decisions.

1. Conceptual Clarity First

Entities must be explicitly defined before they are modeled
Names must correspond to clear concepts
Ambiguous concepts are resolved before implementation

If a concept cannot be explained clearly, it is not ready to be implemented.

2. Documentation Is Part of the System

Design documentation is not an afterthought.

ICT pages are treated as:

Design agreements
Memory of decisions
Context for future contributors
Protection against ad-hoc changes

Undocumented decisions are considered unstable.

3. Slow Down at the Right Moment

Time invested early in:

analysis
reflection
documentation

prevents large-scale refactoring later.

Deliberate pauses before implementation are a feature, not a delay.

4. Separate Concerns Explicitly

The system separates:

Historical reality (HeritageObjects, Actors)
Interpretation and narrative (ResearchChapters)
Representation (DigitalAssets)
Storage (Files)
Technical infrastructure (Cargo, Page Schemas)

Blurring these layers leads to brittle systems.

5. Avoid Premature Optimization and Automation

Automation is introduced only when:

the underlying model is stable
workflows are well understood
manual processes have proven their value

Early automation hides conceptual flaws instead of solving them.

6. Favor Evolution over Perfection

The goal is not a perfect initial model, but a stable and evolvable one.

Changes are expected, but they must be:

intentional
documented
conceptually justified

Schema drift without reflection is discouraged.

7. Implementation Is Reversible; Conceptual Errors Are Not

Technical choices can often be changed. Conceptual misunderstandings are far more costly.

For this reason:

ER models are frozen before implementation
Entity definitions are agreed upon first
Structural changes require reflection

Working Method

The adopted working method follows this cycle:

Think
Define
Document
Review
Reflect
Implement
Evaluate
Iterate deliberately

Skipping steps increases the risk of failure.

Intended Audience

This page is intended for:

System administrators
Editors involved in structural decisions
Future maintainers
Anyone wondering why things are done this way

It is not intended as a technical manual.

Status

This document expresses the current design philosophy.

It should evolve only when experience clearly justifies it.