I'm writing a CSS book

JavaScript archives Compatibility Thidrekssaga QuirksBlog Donations CSS book Politics Mobile About COH

contact

On MDN keeping around outdated information

I made a mistake in yesterday’s article. Not a technical mistake, but an MDN-reading mistake. The reasons why I did so are moderately interesting for MDN users, and suggest a few improvements for the site.

I said that https://developer.mozilla.org/en-US/docs/Web/CSS/:-moz-placeholder did not mention opacity on placeholders. While that’s true, it turns out I really should have looked at https://developer.mozilla.org/en-US/docs/Web/CSS/::-moz-placeholder, which does mention it.

Do you spot the difference? Do you see what I did wrong? Initially I didn’t — it had to be pointed out to me. (Personally I find the whole :: thing a bit of square-millimeter wankery, but I seem to be on the losing side of this particular discussion.)

Search in a hurry

I don’t know about you, but when I visit MDN I’m usually in a hurry. I usually need to know one specific bit of syntax, or a quick “Is this supported at all?” answer. Visiting MDN is not what I’m trying to achieve — figuring out how something works is, and the fact that I have to stop to look it up is mildly annoying to me. So: hurry. Yesterday was no exception.

MDN’s search functionality is not great, but I just looked at yesterday’s query again, and I’m afraid I can’t put all the blame on the search. While it usually gives you all kinds of XUL hits nobody needs, the page I should have been looking at was above the page I actually looked at. And it IS possible to filter results, but the site doesn’t remember your filter. Maybe it should — I’m not sure.

Anyway, yesterday I clicked on the wrong link and ended up here.

Coloured blocks

The page has all kinds of stern coloured blocks that give out Important Information. I don’t know about you, but I never read them, since they occur on nearly all pages and I know in advance they do not contain the information I’m looking for — and I’m in a hurry. Here one of the coloured blocks said Non-standard. I already knew that, thanks so much. Let’s skip to the actual content, shall we?

The thing I looked at straight away was the code example, and it matched what I was trying to do in my test (except for the pesky missing : but I didn’t notice that). The example and explanation text made no mention of opacity, so that’s what I said in my article.

Also, although the correct page mentions opacity in the helper text, it doesn’t use it in the code example, while it should. Changing the colour of a placeholder text requires not only the new colour, but also the opacity. So that’s an actual slight mistake on MDN’s part.

Keeping around outdated information

The fundamental problem here is not the search or the coloured blocks nobody reads, but the fact that MDN keeps around documentation for outdated features. I think that’s a mistake.

I have quite a bit of experience in maintaining large documentation sites (more than MDN, even), and I never do this. When I create a new version of a table I remove the old one entirely in order to avoid confusion. Oh, about once a year I wished I still had a few old bits of data around, but in general this is the best way of handling old content.

If you keep around documentation for no-longer-supported versions of a feature, and if the old and the new name differ by only one :, it’s understandable that people get confused. It might be useful to consider removing these pages, since they have no function any more, and will cause technical bloggers to say unkind things about your otherwise excellent documentation site.