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

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

[emenel@post.lurk.org]

@CorvidCrone this is a big part of what i like about gnu software.

[craigmorgan@mastodon.social]

@CorvidCrone anybody who worked with DEC manual/docsets for software will second this ...

[roundtrip@federate.social]

@Fragarach @CorvidCrone
Yes! A well authored index is much more that a printed replacement for search. It rewards browsing as much as lookup.

One full pass through a good index give you an idea of what a book/paper contains and confidence that you can go back to the index to refresh your memory.

It can even be funny — like Kimbote’s index to ‘Pale Fire’

This seems ok:
https://www.litcharts.com/lit/pale-fire/the-index

[bekopharm@indieweb.social]

@CorvidCrone as a programmer I want ~~to be grabbed by the cheeks~~ such manuals too.

[timwardcam@c.im]

@dequbed @CorvidCrone Microsoft C 7 (IIRC) came in a box a couple of feet long filled with books (a complete set of documentation for Windows development). And a few floppy disks tacked on at the end.

[bluedot@left-bank.net]

@CorvidCrone

How am I supposed to RTFM if they won't give me the F M?

[corvidcrone@kolektiva.social]

@BlueDot exactly!

[rjayne_n@wandering.shop]

@CorvidCrone I, a tech writer, want to WRITE the instructional manual for someone. Really.
Why should your users have a "help chatbot" jumping and swirling in the bottom corner of your screen while you type?

[corvidcrone@kolektiva.social]

@Rjayne_n and the chatbot always pops up over whatever you're looking at

[gandalfdg@indieweb.social]

@CorvidCrone This is how I felt trying to get any sort of idea what the hell a "databricks" is

as far as I can tell it's some sort of marketing website that allegedly can do things with data but without some sort of training I don't think I'll ever really know.

[rjayne_n@wandering.shop]

@CorvidCrone Yes it does. Sigh.
Normally saying "hey are you looking for something?"

... normally it's the button to turn it off.

[stairjoke@indieweb.social]

@Kay Updates shouldn’t break the existing features. changing existing features should be rare, because it breaks learned behaviours. Having to update the manual might be friction enough to save us from ever changing UIs.

[stairjoke@indieweb.social]

@CorvidCrone The manual should include pictures, like the toolbar icon to click, and images that make it plain where in the UI a feature is located.