Use Lists, Not Commas, In Technical Writing


This is an opinion, so feel free to disagree.

My Advice

Whenever you have an enumeration (whenever you list stuff out) that’s written inline with commas, break it off into an explicit list, either unordered (bullet points) or ordered (with 1., 2., etc.).

This makes the enumeration obvious and easier to read.

Examples of Comma Separated Enumerations

Contrived example

A homeomorphism is a bijective, continuous function, whose inverse is also continuous.

Actual Example from a Friend’s Blog

His blog no longer has this, but the original form was:

Pure functions are often defined as those without side effects. Side effects tend to be handwaved as “things that affect hidden state”, “things that are confusing”, “things that are bad that you can do in C++ because C++ is bad”, and other such bogeymen.

Rewritten forms

Homeomorphisms

A homeomorphism \(f\) is a function that is:

  • bijective
  • continuous
  • \(f^{-1}\) is also continuous.

Side Effects

Pure functions are often defined as those without side effects.

Side effects tend to be handwaved as:

  • “things that affect hidden state”
  • “things that are confusing”
  • “things that are bad that you can do in C++ because C++ is bad”
  • other such bogeymen.

Caveats

It’s important to put the redundant info in the header for each list, or else it sounds weird when read.

Example

A homeomorphism is:

  • a bijective function
  • a continuous function
  • \(f^{-1}\) is also continuous.

Repeating “a function” sounds weird.

Takeaway

Go forth and write lists that people can read at a glance. Don’t make your readers work as much as possible, because God knows they’re lazy.

Errors

If you find any errors, or if I’m just plain wrong, or you want to tell me something, feel free to tell me.

Related Posts

Random Thought: LC Theorem

I finally have an answer to "who's your favorite singer?"

My Top Tip for Helping People Get Started Programming

GPT-f

Random paper on angles

An Image is Worth 16x16 Words

Random stuff

Lossless Data Compression with Neural Networks by Fabrice Bellard

Downscaling Numerical Weather Models With GANs (My CI 2019 Paper)

Learning Differential Forms and Questions