Yes. I was thinking about this couple weeks back -- but at that time, I was thinking about creating stub pages at the spec urls that point to the actual specs. But, changing the urls is a better idea.

However, what would serve as a wikitext spec?

However, what would serve as a wikitext spec?

(Half-serious) starting point:

1. Any text is valid wikitext.
2. Some text produces more useful output. See [[Help:Formatting]] for hints.
3. This spec is written in wikitext. Also, see 1).

I think making a spec for wikitext, even if it is mostly just "wikitext is complicated. See [[Help:Formatting]]" is a good start.

When/if we ever write up wikitext/2.0, then the corresponding wikitext spec will (hopefully!) be a lot more definitive, including a short BNF grammar. (Wouldn't it be nice to have a short grammar?)

Although it's always nice to have a formal specification, look at http://daringfireball.net/projects/markdown/syntax for comparison. We could easily write a description of wikitext at that level of detail (ie, not very detailed).

But anyway: the point of making the URL point to a wiki page is that we can improve the spec with time.

+1 on https://mediawiki.org/wiki/specs/html/1.0.0 (although wouldn't there need to be some capital letters in there?)

I would like to propose linking to actual wiki pages documenting the spec instead. An example would be the content of https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec snapshotted at a url like https://mediawiki.org/wiki/specs/html/1.0.0. Updating the spec would entail creating a new subpage. There could be a changelog in there somewhere as well.

+1e3 (at least). I was discussing a similar idea with a similar point with Moritz for Mathoid, so a move like this would really make our content types consistent across the board.

In T110126#1569503, @GWicke wrote:

(Half-serious) starting point:

1. Any text is valid wikitext.
2. Some text produces more useful output. See [[Help:Formatting]] for hints.
3. This spec is written in wikitext. Also, see 1).

Explicitly saying you can write anything - it's free-form is IMHO much better than saying nothing, so I'd take your spec here seriously :)

In T110126#1569962, @cscott wrote:

When/if we ever write up wikitext/2.0, then the corresponding wikitext spec will (hopefully!) be a lot more definitive, including a short BNF grammar. (Wouldn't it be nice to have a short grammar?)

Oh yeah, BNF would help both sides of the fence in the long term, /me thinks.

But anyway: the point of making the URL point to a wiki page is that we can improve the spec with time.

Adding to your point, putting a (functional) URL in the content type is also good because users can read up on the spec the document relies upon, rather than reading about the latest one, which may or may not be what they want (and hence lead to misunderstandings).

Another good point is that users do not (necessarily) need to go look at the docs to find out where the specification is, but rather can see it in the response right away.

+1 on https://mediawiki.org/wiki/specs/html/1.0.0 (although wouldn't there need to be some capital letters in there?)

Clicking on the link suggests just an upper-cased S is enough - https://www.mediawiki.org/wiki/Specs/html/1.0.0 :)

https://www.mediawiki.org/wiki/Specs/html/1.0.0 works for me. To begin, we could just put a #REDIRECT there to stake our claim, and fix it up nice later.

Okay, it sounds like we have a consensus.

Should we make one clean-up pass soon? If so, then we'll need to coordinate on the switch, with the Parsoid deploy happening just before we merge the corresponding RB changes.

In T110126#1573579, @GWicke wrote:

Should we make one clean-up pass soon?

Sounds good to me.

If so, then we'll need to coordinate on the switch, with the Parsoid deploy happening just before we merge the corresponding RB changes.

s/merge/merge and deploy/ - consistency FTW