Is “Syntax” the Problem Here?

Photo by Jorge Rosal on Unsplash

Technical documentation seems promising. It’s a way of communicating important information that software engineers need to share. Clarity is vital to allow everyone to understand the message contained within the docs. 

So why is it that software developers (of all people) seem to struggle with spelling, grammar and syntax? They are essential programming components, so the documentation would be expected to be clear and easy to understand.

Yes. Today I’m writing a blog post about a misunderstanding of when to use quotation marks.

What’s a “Random Forest”?

So I just went to an all-hands call and was given the opportunity to learn something about machine learning as used by my current employer.

Up on the screen, I saw a table containing the following line:

400 separate decision trees make up the “Random Forest”

It’s a gem. Quotation marks around a perfectly legitimate, widely recognized term (and given to a technical audience no less).

This might seem nitpicky, but stick with me. Quotation marks imply doubt, irony, or some offhand commentary that doesn’t belong in a term as precise as “Random Forest.” 

This is an incorrect use of quotation marks that muddy the water and make it feel like the presenter is questioning their own terminology. Are they implying that Random Forests don’t actually exist? Is this some esoteric joke that I, a humble software developer, don’t get?

You know the answer as well as I do. It’s either laziness or a misunderstanding of how question marks should be used. It’s a pity since you’d expect a software engineer to value precision, wouldn’t you?

It’s Poor, Plain and Simple

Simple rules for clarity apply if you are writing English or code.

If you don’t understand a language feature, don’t use it until you’ve read up on it. So, leave the quotation marks out unless they’re used to write sarcastic rants about software developers’ English “abilities”.

We work in an industry where precision matters. Misusing quotation marks might not seem like a big deal, but in a field where the difference between a comma and a semicolon can crash a system, let’s hold ourselves to higher standards.

If we don’t, we risk creating a world where everything is a “Random Forest.” And nobody wants that.

Conclusion

The blog post title is deliberate before you lot start.