A bunch of procedures, common procs and APIs

Writing & Communication

Jargon Is Your Enemy

This is starting to become a sticking point in science, not just in terms of a scientist speaking to a non-specialist audience, but specialists speaking to other specialists from other fields. - An excellent article on excessive use of jargon in biology - excessive because most of biological jargon are just simple words made to sound sophisticated for its own sake (or simple words that got latinized). - Convoluted jargon is expensive - there is a material cost of confusion and miscommunication. - Excessive jargon makes the author sound stupid anyway, because readers can tell if an author is trying to mask his own lack of understanding, or is unable to break down his concepts into simpler terms.

In summary, the point of using jargon in the first place is just as shorthand, when specialists who know what they're talking about want to refer to the same thing repeatedly. When the costs of jargon (alienating your readership, sounding stupid, potential for miscommunication) start to outweigh the (marginal) benefits, stop using jargon.

My Personal Take

  • I avoid jargon, or even big words, because this is not grade school and I don't have a teacher to give me a gold star for showing off your vocabulary. On the contrary, you're more likely, as a reader, to be impressed by a writer who can explain complex ideas in simple terms.
  • Don't write like a scientist. I particularly dislike that writing style in publications which I think of as "academic deadpan".
  • Avoid passive voice. "I baked a cake", instead of "The cake was baked" or "The cake was baked by me", sounds better. A common defence of using passive voice is that it "sounds objective". Don't try to sound objective, just be objective.
  • This applies in a surprising number of fields (personal finance, corporate finance, programming): if you can't explain your plan, it's a bad plan. Sometimes, an even more restrictive heuristic is used: if you can't explain your plan in 30 seconds, it's a bad plan.

Stop Using These Words Forever

  • utilize - "use" is fine.
  • novel - of course it's novel, otherwise you wouldn't be writing about it.
  • morphology - "structure", "form", "shape" are all fine.
  • enrich - if you're a bioinformatician. Many bioinformatics papers use this as a catch-all verb when they can't think of a better word.
  • homologous/conserved - similar is fine. These terms may have some additional connotations in their usual biological contexts, but from a computational point of view, these connotations are usually beyond the scope of the study (i.e. may be true, but we don't care for the moment; can be left for "further research"). "Sequences X and Y showed homologous DNA sections" means exactly the same as "Sequences X and Y showed similar DNA sections", but one is more understandable.

I hate the following words for their non-specificity. A rule of thumb is: if you can replace any of these words with the word "stuff", then it's a useless word. A common statement is, for example: "we conducted phylogenetics analysis", which doesn't tell you much more than "we did stuff." - Analysis/study/investigate - if it's not an operative word that tells the reader what actions I took, it's useless. I'd only use these if my intention is exactly to hide unnecessary, or not-yet-necessary, detail - but this is rarely the case in a publication, or in software documentation (where the point is exactly to tell the reader all the necessary steps). - Model - Again, too vague. Almost all of applied maths is modelling.

More Useful Links

  • See this guideline on how to share data with a statistician.
  • See this stackoverflow post on how to ask a good question. It has a programming bent, but its principles are applicable to any other field - finding the right question to ask is not a trivial problem.