January 12, 2023

HOWTO: WRITE BETTER DOCUMENTATION

So, call to action: if you are writing any kind of documentation, before explaining how to fix the problem, teach the user how to diagnose it.

Source: Why Linux Troubleshooting Advice Sucks

I’ve been writing documentation for myself for years, and been using Linux for 20 years and I still struggle with the basics cos most documentation for Linux fucken sucks.

  • Teach the user how to diagnose the issue so they can confirm the solution you have is indeed for their issue.
  • Explain why this is happening.
  • Provide the solution. Could be a bash one-liner they can copy-paste. Could be a script (explain how to run it). Could be a patch (explain how to apply it). Don’t just say “this is an exercise left to the reader.”

And no, “reading the source” doesn’t help. Neither does “read the man pages”; the only man page worth anything is the one for nmap.

If you’re one of those people that say that you can go fuck yourself, hard, in the ass, no lube.

It’s gentrification by any other name

Not every sector has benefited the same from the influx of digital nomads. Sarai Balderrama, the co-founder of Agencia de Arte, a digital platform that promotes up-and-coming Mexican artists to international clients, told Rest of World, “For over a year, I’ve been trying to tap into that market but they don’t seem interested in staying. You usually buy art when you start calling a place home.”

Source: Digital nomads now come first for Mexico City’s gig workers – Rest of World

The resident population of Mexico City has been screaming at these people to willingly integrate with the fabric of the city instead of just insulating themselves from it. Already thousands have been priced out by these digital nomads.

When Latin American people go to the US or Europe to work, Americans usually scream at them to integrate, and the vast majority of them do, even if they don’t speak the language. They pay taxes, they pay their bills, they spend discretionary income if they have any left after wiring money home.

But Americans and Europeans are not willing to return the favor.