Slide 1
Slide 1 text
Massively increase your productivity on
personal projects with comprehensive
documentation and automated tests
Simon Willison, DjangoCon US 2022
Talk notes are linked from github.com/simonw
Slide 2
Slide 2 text
… aka …
Simon Willison, DjangoCon US 2022
Talk notes are linked from github.com/simonw
Slide 3
Slide 3 text
Coping strategies for the serial
project hoarder
Simon Willison, DjangoCon US 2022
Talk notes are linked from github.com/simonw
Slide 4
Slide 4 text
No content
Slide 5
Slide 5 text
No content
Slide 6
Slide 6 text
No content
Slide 7
Slide 7 text
The perfect commit
Implementation + Tests + Documentation
and a link to an issue thread
Slide 8
Slide 8 text
No content
Slide 9
Slide 9 text
Implementation
It should just do one thing
(“thing” here is deliberately vague!)
Slide 10
Slide 10 text
Tests
Prove that the implementation works
Pass if the new implementation
is correct, fail otherwise
Slide 11
Slide 11 text
Every project should start with a test
assert 1 + 1 == 2 is fine!
Adding tests to an existing test suite is SO MUCH
less work than starting a new test suite from scratch
Slide 12
Slide 12 text
Cookiecutter repo templates
simonw/python-lib
simonw/click-app
simonw/datasette-plugin
Slide 13
Slide 13 text
No content
Slide 14
Slide 14 text
Documentation
Same repository as the code!
Document changes that impact external developers
Update the docs in the same commit as the change
Catch missing documentation updates PR / code review
Slide 15
Slide 15 text
Bonus trick:
documentation unit tests
Slide 16
Slide 16 text
No content
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
Everything links to
an issue thread
Slide 19
Slide 19 text
11 comments
Slide 20
Slide 20 text
What goes in an issue?
• Background: the reasons for the change
• State of play before-hand: embed existing code, link to existing docs
• Links to things! Documentation, inspiration, clues found on StackOver
fl
ow
• Code snippets illustrating potential designs and false-starts
• Decisions. What did you consider? What did you decide?
• Screenshots. Animated screenshots even better!
• When you close it: a link to the updated documentation and demo
Slide 21
Slide 21 text
Temporal documentation
It’s timestamped and contextual
You don’t need to commit to keeping it up-to-date in the future
(but you can add more comments if you like)
Slide 22
Slide 22 text
Issue driven development
Slide 23
Slide 23 text
Don’t remember anything
You can back to a project in six months
and pick up right where you left off
Slide 24
Slide 24 text
Laboratory
notebooks
en.wikipedia.org/wiki/Leonardo_da_Vinci
Slide 25
Slide 25 text
No content
Slide 26
Slide 26 text
simonw/public-notes/issues
Slide 27
Slide 27 text
Tell people what
you did!
(It’s so easy to skip this step)
Slide 28
Slide 28 text
Release notes
(with dates)
Slide 29
Slide 29 text
Expand your definition of “done”
to include writing about what you did
Slide 30
Slide 30 text
Twitter threads
(Embed images + links + videos)
Slide 31
Slide 31 text
Get a blog
Slide 32
Slide 32 text
GUILT
is the enemy of projects
Slide 33
Slide 33 text
Avoid side projects with user accounts
If it has user accounts it’s not a
side-project, it’s an unpaid job
Slide 34
Slide 34 text
If your project is tested and documented,
you have nothing to feel guilty about
(That’s what I tell myself anyway!)
Slide 35
Slide 35 text
Thank you
simonwillison.net
twitter.com/simonw
github.com/simonw