Slides for the talk euclid at mkpm-2011-apr
Euclid,
Socrates
and Mill
-
Quality in
Documentation
-
Quality
-
Perception
-
Observer
-
Observed
-
Observer
Observed
Observation
-
This is
too hard
-
I don't
understand
-
Where do
I start?
-
Aim?
-
"I know
kung fu!"
-
How?
-
Styles of
documentation
-
Qualities of
documentation
-
Euclid
Socrates
Mill
-
Euclid
-
Elements
-
Synthesis
-
Postulates
-
Proofs
-
No forward
references
-
sub foo {
bar()
}
-
sub bar { ... }
...
sub foo {
-
Build up
knowledge
-
Build up
understanding
-
Never say
"trust me"
-
K & R
-
The C
Programming
Language
-
Advantages?
-
Clear
requirements
-
Solid
foundations
-
Always know
where your
towel is
-
Consistent
mental
model
-
Disadvantages?
-
Dry
-
Terse
-
Weak on
"why?"
-
Aristotle
-
Balancing
geometric
shapes
-
Contrived
synthesis
-
Instead:
Analysis
-
Socrates
-
We already
know the truth
-
Work back to
understanding
of the truth
-
Discursive
-
Philosophical
-
Philosophical
(sorry)
-
Conceptual
model
-
Seeking
quality
-
Quality of
understanding
-
Quality of
purpose
-
Bring them
to the truth
-
Bring them
to the good
-
sub getYearOfBirth
sub calculateAge
-
sub year_of_birth
sub age
-
Discuss
why.
-
Discuss
why not.
-
Advantages?
-
Teaches
principles
-
Fuzzy
topics
-
Connects
to reality
-
Connects
to desire
-
Elucidation
of beauty
-
Disadvantages?
-
Subjective
-
Presumes
a baseline
understanding
-
Presumes a
desire for
craftsmanship
-
Anti
JFDI
-
-
Catalyst
Tutorial
-
Old
Tutorial
-
Controller
Dispatch
-
"But this
isn't real!"
-
New
Tutorial
-
Complete
app
-
"Too much
at once!"
-
*grmbl*
-
-
Mill
-
Utilitarianism
On Liberty
-
Utilitarianism
-
Utility
-
Maximise
happiness
-
Ends
Means
-
Maximise
utility
-
Goal
oriented
-
Snippets
-
Recipes
-
Context
-
Sufficient
Context
-
Can be
illustrative
-
Can be
informative
-
Must be
actionable
-
Try
Tweak
Use
-
Cookbooks
-
HOWTOs
-
Advantages?
-
Minimal
requirements
-
Rapid "wow"
moments
-
Sense of
accomplishment
-
Do now,
learn later
-
Disadvantages?
-
Lack of
depth
-
No mental
model
-
Where do
I go
from here?
-
Cargo
cult
-
Must be
supported
-
Learning Perl
Programming Perl
The Perl Cookbook
-
On Liberty
-
Libertarianism
-
NOT the mad
Americans
-
Liberty
-
Freedom
-
Freedom
Happiness
-
(without
curtailing
others')
-
How do we
apply it?
-
Overarching
principle
-
Starting
points
-
Freedom
of choice
-
Freedom
of pace
-
Freedom
of approach
-
Tutorial
Reference
Cookbook
-
Tutorial
Reference
Cookbook
Principia
-
Necessary
but not
sufficient
-
Ways to
start
-
Ways to
play
-
Ways to
experiment
-
Ways to
have fun
-
Ways to
feel
brilliant
-
"I know
Kung Fu!"
-
Gung
Fu
-
Hard
work
-
Ours
Theirs
-
Don't just
document
-
Teach.
-
Any Questions?
https://shadow.cat/
-
Thank You
https://shadow.cat/