# Teaching With Code

Numerics and Condensed Matter through Julialang Jupyter Notebooks

albi3ro.github.io/M4

Christina Lee

## Clarity

>
$>$

## Features

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

### 3x Grammar and Spelling Check

• With a Computer
• Another Person

Size

Color

Location

### 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

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,666