What is the name of your project?
As someone who frequently writes about software and software tools, I am sometimes stumped on how to spell their names. Well, maybe not spell, but definitely capitalize.
Is it this?
my Bash script deleted all my files
Or this?
my bash script deleted all my files
Or the increasingly-popular way inspired by GitHub-flavored Markdown’s tick syntax?
my
bashscript deleted all my files
This last one may be called GNU style as well, as I see it frequently in GNU documentation.
I am going to go ahead and argue right here that the first one is the best. I think it makes sense to refer to the names of software tools using an initial capital letter, like a proper noun in English. The name of a software tool is certainly a proper noun.
Please tell us!
That said, if you, the author, would prefer a certain spelling, tell us. I was inspired to write this post by this FAQ in the scikit-learn documentation
What is the project name (a lot of people get it wrong)?
scikit-learn, but not scikit or SciKit nor sci-kit learn. Also not scikits.learn or scikits-learn, which were previously used.
This is a great practice. Ask the authors if you don't know. Authors please make it known how you want your name to be spelled.
A simple style guide for software
While I’m sure this idea has been done to death, here’s what I’d propose for technical writing that frequently refers to software.
Rules
- Refer to software by name with an initial capital letter and the rest lowercase, like a proper name
Examples
Thus it should be:
I opened up Vim but all I saw was an empty page
And:
Could you help me? The Python install on my computer is borked again
And:
I rewrote it in Rust for fun
Instead of the alternatives. When in doubt, refer to Strunk & White
Reference
Experiment. Over time, I am collecting usage examples and creating a reference for what I think of as the "right way" to spell common words in computing and biology. Sorted alphabetically, with the word in bold type. Trying to keep this list to things you may not find in other style guides.
A
Believe it or not, the name of the software tool AWK is an initialism for the names of its authors and is spelled with all caps. “I used AWK to process thousands of records.”
B
Prefer the capitalization Bash for the Bourne Again Shell, the successor to the Bourne shell (sh). “I see you’re using Bash, so you’ll need the source command.”
C
D
E
F
G
A computer or cluster may have one GPU or multiple GPUs. Short for “graphics processing unit.”
H
I
J
K
L
Transformer models with greater than 1 billion trainable parameters are commonly known as LLMs, short for “large language models.”
M
The different types of RNA are commonly referred to with a lowercase initial letter. Thus, messenger RNA is spelled mRNA.
N
O
P
Q
R
S
Unlike for Bash, always use lowercase sh for the Bourne shell.
T
U
V
W
X
It’s X-ray and X-ray crystallography for the type of radiation and the biochemical technique for determining the shape of molecules.