WoMM, or, Your Audience, Yourself

people love to say "use common sense" or "use your best judgment"

what they mean is "if you do not already know this, you are capable of deriving it trivially from what you do already know"

this is due to a presumption of knowledge

one speaks to be heard, one writes to be read

this is as true for slam poetry as it is for source code

every text is produced for, or to, or at someone

sometimes that someone is a novice sports bettor

sometimes that someone is your wife as she was when you first met day in the park, at the very moment the light caught her hair

sometimes that someone is an ambitious home cook

sometimes that someone is mostly your social studies teacher but also that cute new kid

sometimes that someone is your advisor, two additional faculty members from your department, and an additional scholar from another institution

that someone does not only hear or read but Gets It

they take the text and combine it with all and only what they are to produce exactly what the author wants to be produced (another interview, horniness, knowing 5 exciting color trends for spring, a Pulitzer, &c.)

all and only what they are is what is necessary to combine with the text, because they don't really exist

it's a set

not like a unique thing, like "straight man looking at instagram right now" counts

the Ideal Reciever is often unknown to the author, or may differ from the author's conscious intent

the Ideal Reciever of this post (imo) is literate in english, at least moderately tech-savvy and programming-interested, and tolerant of my bullshit

your Ideal Reciever is always also at least a little You

this cannot be avoided

it is easier to convey meaning to yourself than it is to convey meaning to anyone else

(many people only write or speak to themselves, whether they mean to or not)

some people think they can take advantage of this exploit by only communicating with people sufficiently like themselves

this works until it doesn't (see, e.g. silicon valley over the last 20 years, or the 1996 michael keaton movie Multiplicity)

we as a discipline have largely come to understand the value of repeatability

we have also come to understand that repeatability is born from consistency

(given the same input, the same process should produce the same result)

see: everything from makefiles to distributed version control systems to package management ecosystems to containerization

unfortunately, you cannot containerize people, but all is not lost

expectation

do not be afraid of the expectations you have of your audience

technical writing is real, and strong, and your friend

you're allowed to expect the people reading the comments in your C++ code to know a thing or two about C++

you're allowed to expect the people reading your article in the Journal of the Society of Cinema and Media Studies to know what you mean by "affect"

it never hurts to be explicit and specific: readers should be familiar with...

the less control you have over the constitution of your audience, the more you need to require

documentation of private code that you write for your coworkers should be different than documentation of public code that you write for random strangers

too many expectations can exclude people who might yet benefit, too few can include people who never will

explanation

do not be afraid to set the scene, define your terms, bring everyone up to speed

start from square i where 1 <= i < where you need to be

this is the rhetorical equivalent of static linking and bears the same risks of bloat plus the chance of looking like a condescending turd

making additional documentation "opt-in" in the form of tooltips, collapsible sections, linking to other texts, etc. can help

resignation

do not be afraid of being misunderstood

it's not your fault, but it is your responsibility

like any other error, the response should be determined by its frequency and severity

sometimes WONTFIX is the correct resolution