Optional features are in practice not optional to understand

November 22, 2012

In a comment on yesterday's entry, Aristotle Pagaltzis suggested that Markdown might be acceptable to my coworkers in part because:

It is just HTML! You can type HTML and it will come out verbatim. It's not really a separate markup language (simple or not) so much as a shorthand notation for HTML.

So you don't have to use Markdown's syntax instead of HTML. Forget how to write a link in Markdown? Just write it using HTML syntax. Will work either way.


This is a valuable feature and drastically reduces the learning curve for Markdown for writing things yourself; effectively you can learn bits and pieces of Markdown as you decide they're more convenient than straight HTML. Unfortunately this doesn't help persuade my coworkers to accept it because of a semi-paradox that optional features are in practice not optional.

The easy way to show this is to ask whether or not my coworkers ever need to learn Markdown and if so, when they need to learn it. To start with, if we never use Markdown syntax at all the answer is clearly no. But at that point Markdown isn't doing anything at all (except perhaps getting in the way because we have to escape things so that it doesn't process them); we might as well write HTML files and not process them through Markdown.

But suppose we use some Markdown. More specifically, let's suppose that I write in Markdown (as I'd like to) and my coworkers write in HTML (as they'd like to). Can they avoid learning Markdown? The answer is not really; the moment they want to touch something that I've worked on, they need to learn Markdown. In fact Markdown has a ratchet effect in this situation, in that the moment anyone introduces any bit of Markdown everyone winds up needing to know it in order to be able to understand and work on that bit of the text. If you do not learn Markdown, you're confined to the (probably shrinking) HTML-only content.

This is what makes optional features not optional to understand; they are only optional as long as they're not being used at all. The moment that they get into your codebase (or document base, or anything), you can no longer understand and work on the full codebase without learning them. Either you segment the codebase and responsibility for it or everyone gets to learn the optional feature.

(I have to thank my coworkers for patiently getting this idea through my thick skull.)

As suggested by my use of 'codebase' here, extensions to programming language features (and the use of entire programming languages) are left as an exercise for the reader. Really, there are lots of manifestations of this in development.

Written on 22 November 2012.
« The varying appeal of wikitext and other simple markup
A little Unix difference that irritates: what word erase erases »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Thu Nov 22 00:26:45 2012
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.