799
you are viewing a single comment's thread
view the rest of the comments
[-] corsicanguppy@lemmy.ca 4 points 2 years ago* (last edited 2 years ago)

I worked alongside some technical writers in the early post-y2k years at SCO. This was before they sued IBM for code misuse and died by a million legal and PR cuts, thanks to the 'independent news' site launched by a 'recent ex-employee' to reframe things then and rewrite history after.

We had about 15 tech writers in the company, which when I first arrived seemed like a LOT. I'd never met one, and I'd taken a single tech writing course in college as a filler and found it unchallenging work; so I didn't value them at the time aside from filling a necessary role that your average nerd could surely fill. Then I saw their work; and it was amazing. It's one of the product's strong points, and 20 years later it's still so head-and-shoulders above the similar offerings by others and since, that it's a joy to read when I come across it.

Quite simply put, technical writers explain something in a logical, sensible way, where jargon doesn't blind-side the reader and layout and language are consistent and easy. Hell, spelling is correct; which is a big win over 90% of the current stuff. Tech writers are writers as Lance L said, and thus know about adjective order, prepositional placement, the difference between 'backup' and 'back up' and all its similar terms; and of course know why e-mail and traffic do not get an S as nouns - ever - even if the popular kids make everyone say it without thinking.

It's all simple-sounding stuff, and I was fooled into believing it was mundane; but when put together and written with an eye toward a common style it takes a stressful reader looking for a process or a parameter and induces calm for that brief moment required to get into the doc and find the sought-after bit.

Honestly, like the mentors we lost as a working society in the post-y2k bust when the c-suite cleared the ranks of things they didn't understand, the loss of good technical documentation has a generational effect and will take a massive, sustained effort to reverse.

this post was submitted on 02 Aug 2024
799 points (96.6% liked)

Selfhosted

59939 readers
332 users here now

A place to share alternatives to popular online services that can be self-hosted without giving up privacy or locking you into a service you don't control.

Rules:

  1. Be civil: we're here to support and learn from one another. Insults won't be tolerated. Flame wars are frowned upon.

  2. No spam.

  3. Posts here are to be centered around self-hosting. Please ensure it is clear in your post how it relates to self-hosting.

  4. Don't duplicate the full text of your blog or git here. Just post the link for folks to click.

  5. Submission headline should match the article title.

  6. No trolling.

Resources:

Any issues on the community? Report it using the report flag.

Questions? DM the mods!

founded 3 years ago
MODERATORS