Teaching With Code

Numerics and Condensed Matter through Julialang Jupyter Notebooks

albi3ro.github.io/M4

Christina Lee

Computer Readable Code

Human Readable Code

Beginner

Peer

Performance

Clarity

>
>>

Communication

Features

Simplify

Prototype Code

Simple Code

Explain like you're talking to Grandma

By Source, Fair use, https://en.wikipedia.org/w/index.php?curid=15034811

Separate Tutorials and Documentation

\neq
\neq

Efficienct

Comprehensive

Concepts versus Details

3x Grammar and Spelling Check

  • With a Computer
  • Reading Aloud
  • Another Person

Size

Color

Location

Let the Design do the Work 

Let the Design do the Work 

  • Color Scheme
  • Font
  • Density
  • Busyness
  • Simplify
  • Explain like you're talking to Grandma
  • Separate Tutorials and Documentation
  • Concepts Versus Details
  • Check Spelling and Grammar
  • Let the design do the reader's work for them

Let the Design do the Work

  • Does the design reflect the information?
  • Does the brain know where to look?
  • Does my brain tense up or relax when I look at this?

3x Grammar and Spelling Check

  • Avoid passive sentences

Functors got used.

We used functors.

3x Grammar and Spelling Check

  • Avoid passive sentences
  • Change up the vocab

Int changes to Float.  This change changes the amount of memory allocated.

Int changes to Float.  This conversion expands the amount of memory allocated.

3x Grammar and Spelling Check

  • Avoid passive sentences
  • Change up the vocab
  • Avoid unclear antecedents

Yoshi gave Ichiro a ride home, but he forgot his wallet.

Yoshi gave Ichiro a ride home, but Ichiro forgot his wallet.

3x Grammar and Spelling Check

  • Avoid passive sentences
  • Change up the vocab
  • Have clear pronouns and antecedents
  • Remove filler words

Actually, this sentence basically has a lot of really very awesome words.

This sentence has words.

really

very

Actually

Basically

a lot

Teaching With Code

By Christina Lee

Teaching With Code

Standards already exist to improve software readability, but code understandable by a colleague differs from the best code to present to a student. As a scientist, I have often had to jump from mathematics or pseudo-code to a fully fledged implementation, with no chance to gain purchase in an intermediate middle ground. In the last year, I have worked on a Julia blog in computational physics and numerics and have striven to write code comprehensible to someone unfamiliar with the fundamental principles of the algorithm. In this talk, I will display both good and bad examples of documentation and tutorials, as well as guidelines for improvement.

  • 1,598