MacGyvering your docs

interventions for fun and (non)profit

Paul Roeland / @polyester

press "s" for speakernotes


Know the feeling?

Developers hate you

Users take you for granted

Nobody recognizes all the hard work

All the others have more people / time / money / stuff...

it's all so...


First attempt: Optimism


so we wait

and we ask nicely...



But not from this type of guy...




Put the things you find
to clever use

things you find...

or beg, steal, borrow

long lost friends

interesting places to meet

help from kind strangers

note the recurring theme here?


set agenda

be unavoidable

be tenacious

be unapologetic

put your heart into it

it's fun

* and yup, that's me. Handbag toss at the Drag Queen Olympics. Long story. It had a point.

Method to the madness

Over time, campaigners learnt:

Lasting results need planning

This is NOT serendipity or talent

Theory of Change

Assumption Backwards Mapping Change Framework
Indicator Interaction Intervention
Justification Outcome Framework Narrative
Population Precondition Scope
Target Threshold Ultimate Outcome

The hard ones...

Target: who of the Population?

Scope: where's a sensible limit?

Outcomes → Preconditions →

Threshold: when is it good enough?


  • Enabling environment
  • Capacities strenghtened
  • Alternatives developed
  • Agendas set
  • Policies changed
  • Practice changed

but we want

Real Tools!


Git, Sphinx,

RobotFramework, CI

Use, not abuse

Bliss ?


new rules, new problems

from NonProfit import Obsession
from HumanBehavior import Preacher(*complex)
from Risk import Burn→Out

as it turns out, that Threshold and
Scope part are harder than you think.

Campaigners vs. Techies


more docs? enable contributors!

money is not the issue

you're eyeing social change

so learn the tricks of the trade!

Be prepared to wash, rinse, repeat

Now go fix stuff...

with SKILLZ!

Raindrops on roses

and whiskers on kittens

Bright copper kettles

and warm woolen mittens

Brown paper packages

Tied up with strings

These are a few

of my favorite things