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

[j5v@mastodon.social]

@CorvidCrone I don't have enough soapboxes to empathise fully with your post.

I'm a tech writer and (former?) programmer, with empathy.

[tty@sunbeam.city]

@CorvidCrone You are in good company.

I think, related to this, is that I want software to change more slowly. More contemplation. More thought. More pause. One new version per year, thought through with more intentionality.

[donaldball@triangletoot.party]

@drwho @GentlemanTech @CorvidCrone AWS IAM docs are a trash fire. Half the examples just shrug and use wildcards. String matching, for access control primitives, because not even the insiders have accurate reference documentation.

[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.)