WTFM is fun

There’s a delight in writing documentation, in putting the words down that you wish you could read when first starting to use a project. At that point nothing doesn’t make sense, and everything is going to proceed according to the clear picture you have. Things later change, but when done well I think the earlier documentation serves to get you back on track, and makes later maintenance so much better.

Email-letters

I’ve been attempting to write to people again lately. As in, proper letters on paper and in envelopes and stuck through holes in walls and doors. It doesn’t work though. Ten years ago I wrote to people, and it was reasonably easy although one had to ignore the anachronistic self-consciousness. Now, it feels like writing a telegram, for all the relevance it has to modern life. And doing so on some sort of rare letterpress’d form at that — the mechanics have become harder, the whole thing far less familiar. Where even is there a post box around here? Do stamps still come in booklets? What’s it even cost to send a letter? Only people having weddings send things in the post these days.

I once wrote a little system for writing email-letters. It was a bit like Gmail’s system of having the reply-box at the bottom of the to-and-fro conversation, except it went to further extremes of actually deleting the quoted reply text from emails, and of actually tracking correspondents as entities in their own right and not just by email address. It also prohibited writing to more than one person at once.

It feels like there’s a place for a letter-writing system that really is just email but also isn’t one’s normal email client (be that Fastmail, Gmail, Thunderbird, or whatever). Writing to a friend should be a different act to tapping off a note to a colleague or haggling with a civil servant. The user interface should reflect that. It should be simpler, calmer, and prioritise longer paragraphs and better grammar. (I’ve read similar sentiments relating to the design of the Discourse forum software; the developers of that want the software to shunt people towards better discussions, and I’m pretty sure Google don’t have anything like that idea with the Gmail interface. No one wants to write a letter on a blotter edged with full-colour advertisements for Fletcher’s Fantastic Fumigator, and Google want you to use the exact same interface for work and for social interaction. Doesn’t seem like a good idea to me.)

I’d still be using my email archiver, but it dates from an age before two-factor authentication, and improvements in the security of email providers broke it and I’ve not yet gotten around to fixing it. Perhaps it’s time to do so.

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