Sam Wilson's Website

Another docs-first win (didn't happen)

I was writing some user documentation for RedirectManager just now, and wrote this sentence-and-a-bit:

If you provide a name of an existing page to create as a redirect, an error message will be shown and no redirect will be created. Similarly, if you

I was going to say something about how it’s not possible to create a redirect to a page that doesn’t exist. This isn’t a limitation of MediaWiki, but when I was writing the RedirectManager API I thought it would be good to prevent these “dangling redirects”. It wasn’t until I came to write the documentation that I realised the most obvious use-case: creating a redirect to a page that you’re in the process of creating! As in, while writing a new page, you want to add a shortcut to it — hardly a rare thing, I think.

This is why I really like “documentation-driven development”, where one writes the docs first and pretends that they’re describing features that already exist. It really does help focus the mind on what’s required of the code, and (as in today’s example) highlights things that might otherwise be overlooked.

So I’ll now go and change the API error to a warning, and not show it at all in the UI (although it might be worth having some indication that the target page doesn’t exist).

Tags: · · · ·