rants

Markdown is an excellent choice for documentation

Every few months, it seems a new post decrying the use of markdown for documentation (or other things) rises to the top of Hacker News.

There are often good reasons for preferring a more structured option, like reStructuredText, LaTeX, or Asciidoc. Especially in projects where more formal text is required, or where you need to support specialized and structured text formatting.

But for 98% of software projects (and in my experience, 95% of all other text I've ever written), markdown suffices, and it is truly a low barrier compared to the alternatives. It's basically plain text (which anyone can learn to write in a few seconds) with extra features.

I've written two books entirely in markdown—specifically, LeanPub-flavored markdown—and besides plain text, it is the easiest language for general content authoring.

A Tale of Two Apples: AirPods and the Touch Bar

Yesterday UPS delivered a BTO 2016 MacBook Pro 13" with Touch Bar (to replace my 2013 11" MacBook Air), and a set of AirPods (to replace three different headsets I use daily in my work as a remote employee).

AirPods on 2016 MacBook Pro 13" Touch Bar Safari address bar in Charging Case

The two products tell a different story about the company that makes them:

MacBook Pro with Touch Bar

The MacBook Pro fails to 'thrill' in a way that no other Apple device I've made the conscious decision to purchase has.

Upgrading from a 2013 MacBook Air 11" (portability is king to me, but I needed more performance), the only major external difference is the retina display—something most other 'pro' Mac users have been enjoying since 2012. The Touch Bar itself is mostly useless to me for two reasons:

reCAPTCHAs are easier to read—but they're still a bad idea

From the article reCAPTCHAs are finally readable by normal humans:

Google today announced that reCAPTCHAs served up to humans are finally readable without the need to squint your eyes or bang your keyboard in frustration after typing the wrong sequence of letters five times in a row. Who can even read those things, amirite?

I'm glad Google is making CAPTCHAs easier for humans to read. For the very, very rare times when they're necessary, that's a good thing.

However, I want to make an appeal to the thousands of developers who are thinking of implementing a CAPTCHA to deal with their site's form/registration spam: use CAPTCHAs only as a last resort.

CAPTCHAs - the Nuclear Form Spam Prevention Technique
CAPTCHAs: The nuclear option.

The Drupal Way™

The Drupal Way

I've worked with a wide variety of developers, designers, content managers, and the other Drupal users in the past few years, and I'm pretty sure I have a handle on most of the reasons people think Drupal is a horrible platform. But before I get to that, I have to set up the rest of this post with the following quote:

There are not a hundred people in America who hate the Catholic Church. There are millions of people who hate what they wrongly believe to be the Catholic Church — which is, of course, quite a different thing.

Forgive me for diverging slightly into my faith, but this quote is from the late Fulton J. Sheen, and is in reference to the fact that so many people pour hatred on the Catholic Church not because of what the Church actually teaches, but because of what they think the Catholic Church teaches. Once someone comes to understand the actual teaching, they are free to agree or disagree with it—but there are comparatively few people who disagree with teachings they actually understand.

Similarly, the problems most people have with Drupal—and with systems like it—are problems not with Drupal, but with their perception of Drupal.

Java Jane: One-off vs. Flexible Design

A Java developer (let's call her Jane) is used to creating a bunch of base object classes and a schema for a database by hand, then deploying an application and managing the database through her own wrapper code. Jane is assigned to a Drupal project, takes one look at the database, and decides that no sane person would ever design a schema with hundreds of tables named field_data_* and field_revision_* for every single data point in the application!

Why does Drupal have So Many Database Tables?

In reality, Drupal is doing this because The Drupal Way dictates that things like field data should be: flexible (able to be used by different kinds of entities (content)), able to be translated, able to be revised with a trackable history, and able to be stored in different storage backends (e.g. MySQL, MariaDB, MongoDB, SQLite, etc.). If the fields were all stored in a per-entity table as separate columns, these different traits would be much more difficult to implement.

Thus, The Drupal Way is actually quite beneficial—if you want a flexible content management system.

I think a lot of developers hate Drupal because they know they could build a more efficient web application that only has the minimal required features they need by simply writing everything from scratch (or using a barebones framework). But what about the next 72 times you have to build the exact same thing, except slightly different each time, with a feature that's different here, translation abilities there, integration with Active Directory for user login here, integration with a dozen APIs there, etc.?

There's a maxim that goes something like: Every seasoned web developer started with plain HTML and CSS, or some hosted platform, then discovered a dynamic scripting language and built his own CMS-like system. Then, after building the CMS into a small system like many others but hopelessly insecure and unmaintainable, the developer realized that thousands of other people went through the same progression and ultimately worked together on systems like Drupal. Then said developer starts using Drupal, and the rest is history.

I know you could build a small system that beats the pants off Drupal performance-wise, and handles the three features you need done now. But why spend hours on a login form (that probably has security holes), session handling (ditto), password storage (ditto) forms in general (ditto), content CRUD interfaces, a translation system, a theme layer, etc., when you can have that out of the box, and just spend a little time making it look and behave like you want it? The shoulders of giants and all that...

.Net Neil: Letting Contrib/Bespoke Code Let You Down

A .Net developer (lets call him Neil) joins a Drupal project team after having worked on a small custom .Net application for a few years. Not only does he not know PHP (so he's learning by seeing the code already in use), he is also used to a tightly-controlled application code structure, which he knows and owns end-to-end.

On the State of Drupal Themes and Theming

I was browsing the Drupal Theme Garden a few days ago and was reflecting on how incredibly boring (if not ugly) a large share of the themes looked. Out of all the themes I viewed (over 50), I might consider using only 10 or so on a production site for a quick project that I didn't want to create a theme for.

 No - Yes - Drupal Designs Evaluated

Later on, I read this post on Steven Witten's blog [Acko.net] from 2007, and read through every single comment, because I am extremely interested in the issue of Drupal theming. If you are at all interested in helping Drupal be more themeable and appealing to designers, you must read the post linked to above. Go ahead - read it. I'll wait...

...okay, now that you're back,

A few of the comments in Steve's blog post deserve a mention...

From the blog posting itself: "Not enough Drupal people are savvy enough about theming and design to help out with even small tasks (like a banner) or even give quality tips and feedback on other work. The result is that theming and design receives little attention. Most contributed themes and sites could look a lot better, if they just themed it some more. And getting patches into core that give the defaults a little more oomph is tough, as they are often considered to be useless embellishments.