DEV Community

[Comment from a deleted post]
ikirker profile image
Ian Kirker

This is going to sound a little odd, but I recommend against MediaWiki as a documentation system, having used it as one.

The reasons why have a lot to do with the work people don't see that goes into making Wikipedia usable. It's easy to see that someone has to write Wikipedia articles, but it's equally easy to overlook the many, many hours of community labour that go into making Wikipedia articles look and feel right, link to other related Wikipedia articles, and ensure that orphaned pages are either linked or removed. If you don't put this sort of parallel effort into maintaining your documentation's hygiene and structure, things will get lost, things will get out of date, and your documentation will slowly rot as you add more pages. And that'll mean spending a significant amount of time in the MediaWiki editor, making templates and checking links, and looking over Special pages. It's just not worth it.

This will happen with other systems as well, but MediaWiki seems to encourage it more than others, and it's harder to fix. It does at least have good tools for finding old and unlinked content, unlike, say, Confluence.

For this reason, I think I'd recommend a system whereby you can easily pull out and look at all the content in one go, and operate on it with tools you're familiar with. This essentially means something that brings it out as files, whether it's a Jekyll-style static page generator, or a Gollum-style files+git-based wiki, or a single-page wiki.

For the record, I'm aware there is a contrib git-connector to MediaWiki, but I'm not sure how well it works -- I've only tried it in the hackiest way possible. Even so, and this is another point against it, MediaWiki's format is not widely used elsewhere, and I've not found another system which will expand its templates.