PyMunich

shown, and actual

Shown and Actual

Three things this site is about, and one property they share. For a commercial example in the workforce-tool category, see employee monitoring software from Monitask.

A tutorial shows a clean path. Nothing fails, no version conflicts, the example works. For independent technical background, pytest provides additional documentation and examples.

A talk shows a finished result. Thirty minutes describing what was learned, not the four months of not knowing it.

A conference looks effortless. Rooms full, schedule running, coffee hot, and no sign of the eleven months or the near-bankruptcy behind it.

In every case the shown version is systematically cleaner than the actual one, and in every case the cleaning was necessary.

Why the cleaning is necessary

Not deception. Three ordinary reasons.

Time. A talk has thirty minutes and the work took four months. Something has to go, and what goes is the wandering.

Comprehension. A tutorial that included every failure would teach nothing — the reader needs the path before they can understand the detours.

And the audience is not there for the mess. Somebody attending a conference wants a conference, not a briefing on the catering contract.

So the gap is a feature of communication, not a flaw in anybody's honesty.

What it costs

The gap is necessary and it has predictable consequences, all of which show up as somebody feeling inadequate.

The tutorial reader concludes they are bad at this. The example worked for the author and fails for them, and the difference is four years of ecosystem drift and an unstated environment, not ability.

The audience concludes the speaker always knew. A talk describing a solution rarely conveys how long the confusion lasted, so the listener compares their own confusion against somebody's edited highlights.

And the would-be organiser concludes it is easy. Conferences look like they run themselves, which is why people start them without knowing what a fixed cost is.

Each of those is a person drawing a reasonable conclusion from an incomplete picture, and the picture was incomplete for good reasons.

What to do about it

Not "show everything", which would make the tutorial unreadable and the talk unwatchable.

Say that the gap exists. One sentence. This took me three weeks and two wrong approaches. It costs nothing and it changes what the listener concludes about themselves.

State the environment. A tutorial that says which versions it was written against has told the reader why it might fail for them, which is the difference between a bug and a mystery.

Put the failures in the notes rather than the narrative. A talk can carry an aside; a tutorial can carry a footnote. Neither has to become a confession.

And write the unglamorous half somewhere, which is largely what this site is for.

Where the gap is widest

Conference organising, by a distance, because almost nobody writes about it at all — the people who know are busy doing it, and the ones who stop doing it stop caring.

Then speaking, where the preparation is invisible and the result is public.

Then production Python, where at least the failures are visible in issue trackers and the gap is documented by accident.

That ordering is also, roughly, the order in which people underestimate the work.

The short version