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