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.

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

Literate Documentation: Writing about the code

This morning I’m returning to work on some code that I haven’t touched for a few months, and I’ve been rather dreading getting back to it. I’ve forgotten all the details; never knew many of them anyway. I was working with someone else on this, and so have to get my head around their work too. And of course, all I’m trying to do is modify one little (well, constrained to one package) part of the program.

How to not only get over this being an annoying chore, but actually get excited again about the program? Start at the top, read through all the javadocs, read through the code, and as I go make the documentation better. Write the story of the program — the narrative of the code. Documentation, in my view, should not only be useful and readable and thoroughly explain the code, it should actually be interesting to read!

This is the essence, I feel, of Literate Programming. I know there was much more to Knuth’s idea than verbose code commentary, but the idea of being able to sit down and read a clear human-language expository of a programme is very powerful. The documentation that is produced is a hypertext, but the nodes of it should be complete, interesting, explanations of how the code works and why it was written the way it was.

Documentation

The documenting of how we live, where we live, what we do — that’s what I’m interested in. And it’s a waste of time, really, in that it doesn’t contribute to any of those things (oh, of course that’s simplifying it too much; oh well). It’s also necessary to live, to be of the world, to construct and do.

Being an observer is quite entertaining in its own right. Sitting, looking, writing; it’s a nice enough way to pass the time. I used to do it, alone and with fountain pen and Moleskine, on a street corner; that was good, but around 2001 I found this whole world of people doing and thinking similar things with ‘description’, out here on the web. Such excitement to be found in this throng! So now, I work at documenting and recording, editing wikis and building catalogues — not failing to recognise the recursive, self-modifying way that these activities impact how they’re done, but still aiming at something called ‘neutrality’, or ‘objectivity’ — and slowly watching things take shape. I’d give up, convince myself that this is actually stupid, if it weren’t for the many other people — the bloggers, Wikipedians, urbexers, hipsters — working in a similar vein. It’s the community, engaged with or not, that makes it worth it. (You should, of course, laugh at me for saying this; it’s cliqué and daftness, I know.)

But that’s not always enough, so I step back from the digital agglomeration: being an observer is exhausting, and seems to dull one’s concern about how one’s own life is lead. So, making steps in, for me, and I sew and work wood and brew beer and bake bread; worldly things, bringing sanity.

Anyway, I’m just once again trying to muddle through this dicotomy, and what I say probably isn’t quite on the mark. Unfortunately, the more I think about it, the less I can see a way through; probably not unpredictable, that. Oh well.