Mngr: Created page with "= 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 co..."

2026-01-19T13:07:12Z

Created page with "= 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 co..."

New page

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

ICT:The correct Desing Philosophy - Revision history