Communications

Communications#

Technical Writing#

Jupyter Book#

Jupyter Book is a convenient way to collect technical writing in book format. It takes a collection of Markdown files and imposes a structure specified in a YAML file to allow the production of ebooks in HTML or PDF format.

Once a project is set up you can build a HTML book with:

jb build --all my_repo

where my_repo holds the _config.yaml and _toc.yaml files with the book properties. Here the optional --all flag triggers an automatic rebuild.

To build a PDF book using a Latex backend produces a much nicer output than the default, which produces HTML first and then converts that to PDF. This requires a full local Latex environment, and the command:

jb build --all my_repo --builder pdflatex

Spelling#

Although most publishing packages and IDEs have built-in spellcheckers, sometimes when working with basic document formats, e.g. markdown it is necessary to use external ones. This section has some tips for setting them up.

Hunspell#

Hunspell is a powerful open-source spellchecker library used in Firefox and LibreOffice. It relies on separately installed language dictionaries in a known system location.

To install hunspell on Mac do:

brew install hunspell

Language Dictionaries#

Spellcheckers rely on language dictionaries being installed on the system. On Linux this can often be handled by the system package manager.

For Mac you can get dictionaries from SCOWL http://wordlist.aspell.net/dicts/

They should be downloaded (e.g. from the Sourceforge link) and added to /Users/$USER/Library/Spelling/ on your system.

Language packages#

Python#
PySpelling#

PySpelling is a wrapper over Hunspell (or Aspell) libraries with some convenience features. You can install it with:

pip install pyspelling

You can specify a spelling config file .pyspelling.yml at the project top level, which will look something like:

spellchecker: hunspell
matrix:
- name: Markdown Sources
  dictionary:
    wordlists:
    - wordlist.txt
  hunspell:
    d: en_GB-large
  sources:
  - '**/*.md'
  default_encoding: utf-8

Here we are using the en_GB-large dictionary and hunspell backend. We are checking only markdown sources using the **/*.md pattern. We are also specifying a wordlist.txt file with terms to be defined.

To do the spellcheck you can run pyspelling at the project top level.

Visualization#

Figures, plots and general visualization are an important part of technical communication. Some things to consider when generating plots:

  • See if your results would be better presented in a table - many plots can just be a table

  • Make axis and legend text large relative to the plot contents - it is too small in many plotting library defaults

  • If using a legend place it suitably - it should not overlap the content or look squashed. If needed it can go outside the plotting area bounds, even if not offered by default by the plotting library.

  • Avoid repeating plot elements - if you have multiple plots in a grid see if you can avoid duplicating some features, like the legend.

  • The legend doesn’t need to have a bounding box - many plotting libraries turn it on by default.

  • If you are comparing the same quantity with similar values over multiple plots keep the y axis scale and range the same.

  • Use a suitable number of tick marks - plotting libraries usually include too many by default

  • If the y value is changing quickly relative to the x value consider using a log scale

  • Use a suitable categorical or discrete color map for categorical values (eg series lines) and a continuum one for continual values - e.g. something that is increasing or decreasing.

  • Avoid relying heavily on color to distinguish plot elements - consider line weight, dashing and point markers to help. If relying on color use a color map that is color-blindness friendly.

  • Avoid having too much text in the plot - include the plot in a text document if more context is needed. Plot titles should only be used in standalone plots, not those included in a text document. Standalone plots need more care in design and should probably be rarely used.

  • Axis text should include units where appropriate.

  • Use Latex for non-trivial symbols

  • Make the plot reproducible - e.g include the data in a text format also, such as a table, csv or json.

  • Consider the output format - default low res PNGs are generally low value. Consider SVG for saving in a repo or high quality rendering - however make sure the plot is faithfully reproduced, especially text positioning. PDF is a good format for high quality publication with Latex.

Architecture Diagrams#

Contents