Sorry for the repetitive title, but Apache Taverna is preparing a release that will include the Taverna Commandline Tool, or is it Command Line Tool, or Command-Line Tool? Or just Command Line?  Now you see the problem. The name for the tool is different throughout the documentation. Not good.

The project lead, not a native English speaker as it turns out, requested that those of us who are native English speakers weigh in on the correct name for the tool. Challenge accepted. How hard can this be? I know compound adjectives are frequently hyphenated when they modify a noun (think, Red-headed woodpecker), but maybe there is a different software-development convention for this particular term?

First, look online

It turns out there is some inconsistency in the online use of command line tool versus command-line tool.  First, I found some examples without hyphens: What is the Command Line Tools Package? and Top 10 Command Line Tools. Then I found a different use, from Wikipedia, that was hyphenated: Command-line interface. But the article has an “issues” flag and, oh yes, it’s Wikipedia; not a good academic reference. I next found Command-Line Reference from Microsoft – with a hyphen. And then I found another from Microsoft, this time without a hyphen: Using command line tools for networking information. And finally, two more from Microsoft – with hyphens: Windows 7 command-line tools and programs and How to create a command-line toolkit for Windows. It seems like the hyphens have an edge, but I wanted a more definitive answer.

Better idea: Look for writing references

Belatedly, I decided to focus on editing and writing resources. I found a useful article about hyphenating compound words, which gave examples of closed compounds (like “flowerpot”), hyphenated compounds (like “merry-go-round’), and open compounds like “school bus.” (Nothing like a good grammar-refresher!)

Following the article’s lead, I first looked in a dictionary, but nothing like command line tool was in any of the online technical dictionaries I found. Next, the article suggested using a style manual. Well, not only are style manuals unlikely to cover command line tool specifically, but

“… the Chicago Manual of Style [at least] has a lengthy section devoted to compound words–evidence that the rules are not simple. Unfortunately, on this issue even the fairly straightforward rules about hyphens leave some room for a writer’s own judgment. ” (Get It Write, 27 April 2003)

So, it’s not simple, and we have to use our judgment. Fortunately, the article gives some direction in this statement quoted from the Texas Law Review Manual of Style: “…join the words by hyphens if doing so will significantly aid the reader in recognizing the compound adjective.”

I can work with that.

Okay, but what about capitalization?

At this point, you will probably not be surprised that when it comes to title capitalization, there is disagreement among the various style manuals. I think I like Command-line Tool, which agrees with the Microsoft technical style manual (referenced here).

So, what’s the bottom line?

The Apache Taverna project does not have a style guide (other than what I’m putting together) and is not following APA guidelines or the Chicago Manual of Style. In true open source fashion, we decide what makes sense for Taverna.

When I throw my two cents into the discussion, I’m going to propose the following rules for writing about the Taverna Command-line Tool.

• Use Taverna Command-line Tool when talking about the tool and in titles. For example, Taverna Command-line Tool (as a title) or “The Taverna Command-line Tool relies upon …” (in a sentence).

• Use all lower case (command-line tool) when talking about generic command-line tools. For example, “The Taverna Command-line Tool is one of two command-line tools…”

• Other acceptable ways of referring to the Taverna Command-line Tool (and variations) are:
  • Command-line Tool
  • Apache Taverna Command-line Tool
  • Apache Taverna Command-line product

• Avoid:
  • Taverna Command-line (always use “Tool”)
  • Taverna Command line Tool (always hyphenate)
  • Taverna Command Line Tool (always hyphenate and use lower case “l”)

Source code and artifacts may break the rules

We will likely break these rules when it comes to source code and artifact names. And I’m fine with that because they were created to improve clarity and understanding for developers, contributors, and users. Sometimes you increase clarity by making rules, sometimes by breaking them. The main thing is to keep your goal in mind. We want to make Apache Taverna code and documentation as clear as possible.

Easy to read, easy to use, and easy to contribute to. That’s what makes open source work.