Tuesday, February 11, 2020

"Simple" Doesn't Always Mean It's Actually "Simpler"

Let it be known, if you're part of the group of people that have been foisting "simplified" markup tools on the community at large, I probably want to chop you in the adam's apple. HTML just ain't that hard to learn, especially the basics you'd need to do project documentation. And, if you find that your "simplified" documentation-language isn't sufficient to documentation tasks, the solution isn't to continue down the path of making your "simplified" markup language more complex. That's simply a sign that you screwed up and should probably set fire to what you've done to date.

We've been through this before with the whole "SGML was too hard, let's create HTML" debacle. I don't want to be back here again in 10-15 years having to deal with a plethora of new "simplified" markup languages just because today's "simplified" markup languages have become too complex.


  • A dozen plus flavors of things all claiming to be "markdown" isn't an improvement over knowing basic HTML and CSS
  • Having to differentiate the subtleties between each of the flavors isn't an improvement over knowing basic HTML and CSS.
  • Relying on bridge markup tools like reStructured isn't an improvement over knowing basic HTML and CSS (especially if I have to pollute my markdown with it). And, frankly, its syntax is more clunky and gibberish than either HTML or even troff/nroff.

Knock off the sprawling simplifications. You're not improving things, you're making things even more of a shit show (and, by extension, further discouraging people to write documentation at all).

1 comment:

  1. Nice. True. There's a chance I might be slightly biased in this, I used to teach code-only HTML/CSS class (pure text class, no graphical interface) for a company.

    ReplyDelete