The pleasures of style guides
We create style guides because they are ergonomic. A terrible term to describe something so beautiful. Style guides let users access information intuitively. They are not dictators. Strive to communicate first and be
Each project requires its own active lists such as:
- Acronyms (& Conventions)
This page exists to provide an explanation of the data a style guide may need for each separate project, as well as styles for reporting data.
Many fields are rife with acronyms. Be warned if you ever work in Education you will experience an avalanche of acronyms.
Language may be used to communicate or to obfuscate. Your decision to be a writer should predispose you to the communicating side. Therefore, challenge yourself everytime you accept an acronym on your list.
- 3 or
lessuses? Then remove it.
- does it assist?
- keep a running list
There are times when over definition may assist, for example at the first use of a chapter.
You may also be writing for challenging subjects, such as the Sciences where the acronym is creeping into use as the term, and therefore both an acronym list and a conventional term list is required.
Conventions; novel thoughts to words
Creating a conventions list for each project makes sense. By keeping this list with the acronym list, you can quickly verify that you have no duplicate terms creeping into use. This can happen when certain fields collide.
There are certain terms in science that enter the vernacular fast,
- AIDS (acquired immunodeficiency syndrome)
- ADP (adenosine diphosphate)
- ATP (adenosine triphosphatase )
- AMP (adenosine monophosphate)
- CFU (colony-forming units)
DNA-related conventional terms
- DNA (deoxyribonucleic acid)
- cDNA (complementary DNA)
- DNase (deoxyribonuclease)
- dsDNA (double-stranded DNA)
- EC50 (half-maximal effective concentration)
- ED50 (half-maximal effective dose)
- EDTA (ethylenediaminetetraacetate)
- ELISA (enzyme-linked immunosorbent assay)
- EM (electron microscopy)
- ER (endoplasmic reticulum)
- HIV (human immunodeficiency virus)
- IC50 (concentration giving half-maximal inhibition)
- IFN (interferon)
- Ig (immunoglobulin)
- LD509 (half-maximal lethal dose)
- mAb (monoclonal antibody)
- MRI magnetic resonance imaging)
- MS mass (spectrometry/spectroscopy
- PCR (polymerase chain reaction)
- PFU (plaque-forming units)
- RNA (ribonucleic acid)
- cRNA (complementary RNA)
- dsRNA (double-stranded RNA)
- gRNA (guide RNA)
- mRNA (messenger RNA)
- miRNA (micro RNA)
- rRNA (ribosomal RNA)
- RNase (ribonuclease)
- tRNA (transfer RNA)
- siRNA (small interfering RNA)
- shRNA (short hairpin RNA)
- UV (ultraviolet)
Then there are the abbreviations- these may be used in figures and tables without definition.
- amt (amount)
- approx (approximately)
- avg (average)
- concn (concentration)
- diam (diameter)
- expt (experiment)
- exptl (experimental)
- ht (height)
- mo (month)
- mol wt (molecular weight)
- no. (number)
- prepn (preparation)
- SD (standard deviation)
- SE (standard error)
- SEM (standard error of the mean)
- sp act (specific activity)
- sp gr (specific gravity)
- temp (temperature)
- vol (volume)
- vs (versus)
- wk (week)
- wt (weight)
- yr (year)
Remember that n, is not N. The larger represents the total sampled population, whilst n represents a sub-population.
If variation within a treatment (coefficient of variation, the standard deviation divided by the mean) is small (less than 10%) and the difference among sensitive means is large (greater than 3 standard deviations), it is not necessary to report statistics. If the data do not meet these criteria, however, then include an appropriate statistical analysis.
Consideration of the limitations of the analyses must also be provided, e.g.:
- multiple comparison issues
- correlation v causation issues
- sample size issues
- sample error issues
Style guide further thoughts
This scratches the surface of the data-side of style guides. There are other lists that may be kept. Standard terms, for example, where you have made a call on which phrases are hyphenated and which, words.
Standard no hyphen terms
- worldwide (not
world-wide) coinfected extraintestinal
For an overview of good practice with API docs see here.