MediaWiki Documentation Day 2017

It’s MediaWiki Documentation Day 2017!

So I’ve been documenting a couple of things, and I’ve added a bit to the Xtools manual.

The latter is actually really useful, not so much from the end-user’s point of view because I dare say they’ll never read it, but I always like writing documentation before coding. It makes the goal so much more clear in my mind, and then the coding is much easier. With agreed-upon documentation, writing tests is easier; with tests written, writing the code is easier.

Time for a beer — and I’ll drink to DFD (document first development)! Oh, and semantic linebreaks are great.

Adding data, not systems

For the most part, and leaving aside some tool-making or data-checking programming, I think it is far more relaxing to add data to the world than to add more systems-for-working-with-data. Contributing to Wikisource, Openstreetmap, Commons, even Flickr and Reddit, will further the cause (what ’cause’?) more than building some new system for cataloguing photos or conducting conversations.

So take photos, draw maps, write blog posts, explore the world and record what you see. Don’t devise the means to do these things — we already have the means, and have had for a rather long time. Better to get on and do it, I think. The means won’t be perfectly what you’d prefer, but then they never will be (even after you’ve built the system that’s perfectly exactly what you want).

If you see what I mean?

Anyway, I’m only saying this because I’m going to be away from regular coding for a few months from next week, so shall be focussing on Doing more than Building. And I can’t wait!

Enable Left Win as the Compose Key on Ubuntu

It is very easy to type “special” characters on Linux (i.e. those that aren’t printed on the keyboard). It’s called the Compose or Multi Key, and it’s brilliant.

First, enable it in ‘Keyboard settings > Advanced > Position of Compose Key’. I’ve got it set to Left Win because I never use that for anything and it’s in a similar position to the key on Apple computers that serves a similar purpose (but whose name I cannot remember).

If the Left Win option is missing (as it seems to be on some Ubuntu installations), you just need to edit /etc/default/keyboard and set:

XKBOPTIONS="compose:lwin"

Then run:

sudo dpkg-reconfigure keyboard-configuration

Once it’s all working you just need to look up the characters you want (Tim Starling also has a good list).

Stop inventing new ways of doing things

Every so often I write this same thing. It’s Monday (any Monday) and so it’s time to write it again.

The solution to very few problems is to write more code. Usually, it is better to write things in English, explaining whatever the thing is.

This is mainly because it takes a good long while to write code, and continues to take time for as long as the codebase exists. This time is better spent actually doing something — code is pretty much always ‘meta’ work, work that supports other work.

And don’t go saying that all work is like that, because it’s just not. (Hurrumph.) Working on preserving, describing, and storing all the books of the realm is work that has value in itself; writing the software for doing that is meta-work. I’d rather work on the former.

Stop inventing new ways of doing things

Every so often I write this same thing. It’s Monday (any Monday) and so it’s time to write it again.

The solution to very few problems is to write more code. Usually, it is better to write things in English, explaining whatever the thing is.

This is mainly because it takes a good long while to write code, and continues to take time for as long as the codebase exists. This time is better spent actually doing something — code is pretty much always ‘meta’ work, or work that supports other work.

And don’t go saying that all work is like that, because it’s just not. (Hurrumph.) Working on preserving, describing, and storing all the books of the realm is work that has value in itself; writing the software for doing that is meta-work. I’d rather work on the former.

Ghost for blogging?

As much as I don’t really know why people can’t just host their own blogs, I think this sort of service is pretty great:

Ghost has initially launched to a small group of investors who donated money through Kickstarter, the crowdfunding website.

The minimal structure and design reflects the ethos of other pared-down blogging platforms such as the US rival Medium, but the British pair have incorporated Ghost as a not-for-profit and are using income to fund development of the site.

Ghost: the UK blogging platform that won’t and can’t sell out to Facebook, Alex Hern, 23 September 2013.

Glossaries in Semantic MediaWiki

A simple glossary system for Semantic MediaWiki that lets you define key terms for use in technical documentation etc.

A term can be referenced from anywhere in the wiki with {{defined term inline|term}}. This results in the term being displayed in a distinct style (green for instance) and linked to the term’s wikipage. When a user hovers over the link, a tooltip is displayed that contains the term’s definition.

Software required: MediaWiki, ParserFunctions, SemanticMediaWiki, SemanticForms.

Pages required:

  1. Defined terms
  2. Template:Defined term
  3. Template:Defined term inline
  4. Form:Defined term
  5. Property:Definition
  6. MediaWiki:Common.css (to change the style of the inline terms)
  7. MediaWiki:Common.js (to fix the tooltip display)
  8. Category:Defined terms (no content actually required, but probably should at least be categorized)
  9. Data pages

Continue reading Glossaries in Semantic MediaWiki

If all you’ve got is a hammer…

(…nail Markdown to a plank.)

Dear everyone: Please Stop Using Markdown For Absolutely Fucking Everything.

In 1984, the first Macintoshes shipped with MacWrite. To get bold text, you pressed command-B, and it appeared bold on-screen. To get italic text, you pressed command-I, and it appeared italic. And so on.

This was pretty much a universal standard until Markdown came along. Now, you press shift-8 to get an asterisk. Then you press shift-8 again. It doesn’t appear bold on-screen, it appears like, well, something with two asterisks next to it.