Technical Writing Style Guide

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 aware when your system starts moving you away from that as a goal. Remain flexible, consider your audience and subject.

Each project requires its own active lists such as:

• Sources
• 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.

Acronyms

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 less uses? 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.

Conventional Terms

There are certain terms in science that enter the vernacular fast, consider: ATP, dAMP, GTP, ATPase, and dGTPase. Far easier to handle than adenosine triphosphatase and deoxyguanosine triphosphatase, etc.

• 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)
• HIV-1
• HIV/AIDS
• 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 related:

• 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)

Abbreviations

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)

Analyses

Analyses creates data and data have units. Therefore, always report numerical data in the appropriate SI units. Means are reported with their n and s.d. (sample size and standard deviation).

Remember that n, is not N. The larger represents the total sampled population, whilst n represents a sub-population. 

Statistics

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

API documentation

For an overview of good practice with API docs see here.