this post was submitted on 21 Apr 2025
1201 points (99.5% liked)
Programmer Humor
22872 readers
994 users here now
Welcome to Programmer Humor!
This is a place where you can post jokes, memes, humor, etc. related to programming!
For sharing awful code theres also Programming Horror.
Rules
- Keep content in english
- No advertisements
- Posts must be related to programming or programmer topics
founded 2 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
Look, computers are like idiot savants - incredibly fast and capable of doing all sorts of things with mindless determination, but without a shred of common sense - so when you're programming you have to literally explain everything including what for you is obvious and there is a whole class of bugs (around corner cases and boundary conditions) related to the programmers not explaining absolutelly everything and forgetting some really rare or unusual situations.
For documentation purposes one should assume that at least some users are like computers, without the savant part.
I write mine with a simple mindset: "imagine we go outside with a net, catch a random person off the street, sit them at the PC and tell them to do X. Will they manage, following this documentation?"
I also number every step (even if they're stupidly simple and could technically be jumbled into a single sentence), so that when a user calls me asking for help with something documented, all I need to do is ask them "at which step of the instructions are you encountering the problem", and then they hang up because they never read the instructions in the first place. Saves a lot of hassle!
I really like the social engineering element of your documentation strategy!