*gently grabs the cheeks of all programmers to stare deeply into their eyes*

[bms48@mastodon.social]

@CorvidCrone Have you tried FreeBSD man pages? I wrote a ton of them in 2003.

[bms48@mastodon.social]

@CorvidCrone Oh OK. Sorry to hear that. I thought you were inquiring generally as to who writes "proper manuals"; FreeBSD generally tries to do that with traditional UNIX-style manual pages. I hope you find your tech writer.

[corvidcrone@kolektiva.social]

@bms48 I just want programs that average people have to use to come with actual instructional manuals.

Like I said, my rice cooker came with an extensive instruction manual, including what sounds are normal and what sounds are cause for concern.

My Subaru also came with an actual user manual, so years after I bought it used, I can still look up what that suddenly flashing new alert icon is for and address it before it becomes an expensive problem.

[wbpeckham@techhub.social]

@CorvidCrone you used to get these with some pieces of software. Back when software was for CP/M or DOS. What the heck happened?

[failedlyndonlarouchite@mas.to]

@CorvidCrone

ahem, is there a manual for mastodon ? bluesky ?

[mjj@mstdn.dk]

@CorvidCrone A series of promotional learning videos, gotcha. Coming right up

[the_grue@digitalcourage.social]

@chrisgerhard @CorvidCrone this, plus the very nice info pages for more structured details. Preferably read in #emacs, but there are plenty alternatives.

[dan_turner@cosocial.ca]

@CorvidCrone GIVE ME MAN PAGES OR GIVE ME DEATH

[moopet@toot.cafe]

@CorvidCrone the ZX81 BASIC manual is my role model

[dancast@wandering.shop]

@dequbed @CorvidCrone I remember when all tech manuals, and really, it was all of them, had an ASCII chart in the appendices

[gunstick@mastodon.opencloud.lu]

@CorvidCrone
I learned my programming skills with books listing all instructions in ALPHABETICAL order with explanations.
I just went and read it all from A to Z. And then I knew how the language works.

[djmitche@fosstodon.org]

@CorvidCrone so much this, for tech tools too. The datadog docs are all marketing crap and installation guides with very little actual information, for example. https://diataxis.fr/

[johnkavs@mastodon.ie]

@CorvidCrone preach!

[glc@mastodon.online]

@CorvidCrone

If this happens to be the sole surviving text of our civilization it will leave a good deal of room for interpretive detail.

Though for the most part they'll just label it as obscure religious poetry, much as they did for a century or so with the commercial bill of lading figurines that turned out to be the actual origins of the alphabet, on a closer view.

[corvidcrone@kolektiva.social]

@glc I would be honored if one of my social media posts became the sole surviving text of our civilization.

Honored and horrified.

[glc@mastodon.online]

@CorvidCrone

Good company.

https://en.wikipedia.org/wiki/Complaint_tablet_to_Ea-nāṣir

[cavyherd@wandering.shop]

@ferricoxide @CorvidCrone

This is, in principle, how things should work.

This, of course, depends on the documentation writer being a competent communicator. Which, in the tech world certainly, is by no means a given.

The above is also true of websites.

But figuring out what the writer called the thing, and where they put it....

This can be a challenge.

(To be clear: hard agree.)

[cavyherd@wandering.shop]

@darkling @CorvidCrone

Oh, that's very good! Yes, that definitely seems like that would be the software equivalent of "measure twice, cut once."

Much easier to write the software when you know ahead of time exactly what you're trying to do.

Probably not much into the whole "vibe coding" thing, I'm guessing? (Runs away & hides behind a chair )

[justinderrick@mstdn.ca]

@dequbed @CorvidCrone Story time!

When I started a new job in the IT department of my company, I got sent for a week of training in the US. I got back with a brain full of new information and skills.

A few weeks later, I arrive at my desk, and someone is apparently using it for storage -- there are a dozen extremely heavy boxes, on my desk, on my filing cabinet, on the floor...

My mentor stops by, says "Oh, good. You got the manuals I ordered."

AIX, DB2, ADSM, CMOD, and others...

When I asked where I was supposed to put them, and how I was supposed to organize them, he said "Oh, I think they're already indexed by weight."

I actually read them. All of them.

[bondo@mastodon.social]

@CorvidCrone @jackbrewster This made me happy to read.