Telephone +44(0)1524 64544
Email: info(at)shadowcat.co.uk

Sat Dec 22 00:30:00 2012

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/