On Mon, Dec 29, 2025 at 02:37:02PM +0000, Steve McIntyre wrote:
> So... where are we up to? What are the next steps to making this happen?
Sorry for my extended radio silence around here - life got in the way, and
I've been struggling to wrap my head around a wider problem...
I had thought of migrating the wiki as like translating a software project from
Perl to Python - some differences of emphasis, but basically equally expressive
languages. I've now come to realise it's more like migrating from Subversion
to Git - everything looks the same on the surface, but subtle technology
changes lead to massive cultural changes.
Just as git introduces distributed version control, MediaWiki introduces
template transclusion. This seems like a small thing at first - slightly more
generic templates, and that's all. But actually it allows editors to move from
an *imperative* style to a *declarative* style, which changes everything.
To explain, I'll walk through three examples: translation headers, admonitions
and FAQs.
== Translation headers ==
Here's the translation header in DefaultTemplate[0]:
##For Translators - to have a constantly up to date translation header
in you page, you can just add a line like the following (with the comment's
character at the start of the line removed)
##<<Include(DefaultTemplate,
,from="^##TAG:TRANSLATION-HEADER-START",to="^##TAG:TRANSLATION-HEADER-END")>>
##TAG:TRANSLATION-HEADER-START
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]:
[[DefaultTemplate|English]] - [[es/DefaultTemplate|Español]] -
[[fr/DefaultTemplate|Français]] - [[sr/DefaultTemplate|српски]]-~
##TAG:TRANSLATION-HEADER-END
----
This specifies the exact formatting to put in the wiki, with translations
managed manually. In other words, editors are required to specify the exact
actions they want the renderer to take - an *imperative* style.
The new wiki's ExampleForTranslation[1] header just contains this:
{{PageHeader}}
Among other things, the template generates a translation header automatically
based on other matching page names. In other words, editors are expected to
specify a high-level goal and trust the wiki to work out the details -
a *declarative* style.
Translating from imperative to declarative isn't just a change of syntax.
It means fundamentally reinterpreting what the editor was trying to say,
in a way that requires them to give up control of formatting details.
In practice, this particular example is relatively easy to migrate. If someone
writes a header with commas instead of dashes, or forgets to remove a dead link
to an old translation, they're unlikely to complain if that changes.
The work I've done so far has focussed on standardising bits of markup where
nobody really cares about the details. I lost momentum as I started to see
more controversial examples.
Aside: ExampleForTranslation is a good example of this concept, but see
Recommendations#Language_tags[2] for better translation solutions.
== Admonitions ==
MoinMoin admonitions are boxes to highlight a piece of text. The help page[3]
implies you should format them with a bold heading followed by a single
paragraph of text, but that rule isn't enforced anywhere. If you grep the
archive for `{{#!wiki`, you'll find many examples of admonitions that don't
fit the pattern.
If you don't have access to the archive, compare e.g. AdditionalPHPVersions[4]
to DebianEdu/PageFragment/ObsoleteRelease[5]. The former has an admonition
with the undocumented type "red/solid", a heading, a few paragraphs, a
sub-heading and another paragraph; the latter has an admonition of type
"caution" with a single line of text.
These admonitions make perfect sense given MoinMoin's imperative style -
the editor states what the page should display, and the wiki displays it.
But how would you fit the above examples into MediaWiki's declarative style?
Consider a template like this:
{{Admonition|Type=<some type>|Heading=<some heading>|Body=<some text>}}
Should we support `Type=red/solid`? The box looks OK in the current wiki,
but would look awkwardly retro next to a modern MediaWiki layout. And should
we treat the one-line admonition as a header without a body, or a body without
a header?
The underlying problem is that we can't tell what the editor was trying to say
well enough to agree a migration, and any guess will alienate some editors.
Does that mean we should declare that to be bad documentation and push editors
to be more declarative, or that the declarative style encourages centralisation
that harms our community?
== FAQs ==
The wiki is full of FAQs. MoinMoin doesn't provide anything to support them,
so people just format them however they like. If you grep the archive for
'=.*\(FAQ\|Question\|Q *\& *A\)', you'll find examples with various styles.
If you don't have access to the archive, compare e.g. DebianTrixie[6] to
Mobian/FAQ[7]. The former contains a FAQ section near the bottom, implemented
as a definiiton list; the latter is a whole-page FAQ implemented with headings
and bodies.
Again, this makes sense in an imperative-only wiki - different editors like to
write different FAQs in different styles; readers rarely see more than one
FAQ, so they don't care; and the few of us that scour the wiki for these things
don't have the time to enforce a standard.
In a wiki that supports a declarative style, other solutions become possible.
For example, it would be trivial to create a template of the form
{{FAQ|Question=...|Answer=...}}. In fact, it would be easier to create such a
template than to check if one already exists, or to redesign an existing
template that doesn't support your use case.
This points to another problem - we can't just stand back and allow both
declarative and imperative styles. The declarative style is more efficient, so
it will eventually take over unless we do something drastic like restricting
edits to the `Template:` namespace. And if we don't shape the process,
we'll end up with an unmaintainable mess of overlapping templates.
== So what do we do? ==
Declarative editing is more efficient than imperative editing, and leads to
documentation that more clearly conveys editors' intent. I think we should
embrace it, look for ways to support editors who want to take their time,
and find productive avenues for people who want to go faster.
The best way to do that is to have two migrations: the current *revamp*
rewrites the existing wiki and makes imperative markup easier to find; then we
move straight to a *rewrite* where we really embrace the declarative style.
To give a concrete example of how this would work - I'd recommend
migrating `{{{#!wiki red/solid ... }}}` to a pair of templates
`{{MoinWiki/Start|red/solid}} ... {{MoinWiki/end}}`. Then as soon as we're on
MediaWiki, we can encourage people to go through the list of pages that link to
`MoinWiki/Start` and manually rewrite them to use a nice MW-style {{Note}}.
[0] https://wiki.debian.org/DefaultTemplate
[1] https://wiki2025.debian.org/index.php?title=ExampleForTranslation
[2] https://wiki.debian.org/DebianWiki/WikiRevamp/Recommendations#Language_tags
[3] https://wiki.debian.org/HelpOnAdmonitions
[4] https://wiki.debian.org/AdditionalPHPVersions
[5] https://wiki.debian.org/DebianEdu/PageFragment/ObsoleteRelease
[6] https://wiki.debian.org/DebianTrixie
[7] https://wiki.debian.org/Mobian/FAQ
