Hacker News new | past | comments | ask | show | jobs | submit login

Markdown has a lot of faults, but it solves the one single biggest problem in writing documentation that basically overrides every single other consideration: getting people to actually write it. Basically nothing else matters except this.

And I disagree about the portability. Write Pandoc-compatible markdown and you can convert it to just about any format under the planet. I love that I can write in Markdown, then quickly create a word document to send around the office for comments - whatever anybody says about Word, the track changes and review functions both useful and defacto standards in most offices.

Markdown has always seemed to me less like a file format or a formal document syntax and more like a set of strategies for upsampling plain text into such a structured format by looking for the sorts of informal conventions people naturally use when they're writing plain-text documents.

Or - I should say, it infers structure from the sorts of things people did as a matter of course back when we had a network culture based on sending each other blobs of text via email or Usenet. I'm sure the original author of Markdown.pl was not intending to design a new structured document language at all, and simply wanted to pretty-up some plain text files for display on the Web. The structure was already there, the conventions were already in common use, and Markdown.pl was just one strategy for doing something useful with them.

I think it's easy to get people to use Markdown because it doesn't feel like writing in code, and it doesn't feel like writing in code because it's basically just the sort of thing we all did all the time before the web took over.

Ironically, then, I think it actually will make Markdown less useful to build it up as a rigidly specified uniform document protocol offering sophisticated formatting features. There's certainly value in having the various makers of tools doing this job work together toward a common understanding of the patterns people like to use, but it's far less important whether someone uses triple-tickmarks for quoting or four-space-indentation for quoting or whatever, so long as the tool can recognize that they are doing something, take a reasonable guess at what that might be, and then offer a simple way to correct that guess later if the user is particularly concerned about the way the text is being rendered.

this is an astute comment. (because marssaxman.)

but the problems arise because different markdown flavors recognize different types of "common understanding of the patterns people like to use", so misunderstanding happens.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact