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

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

[exec@furry.engineer]

@CorvidCrone

Go get yourself a technical writer if necessary.

Oh, great. I "got" one. My bf is one.

But he's currently laid off, but not because of AI but because of outsourcing.

[dancingtreefrog@mastodon.social]

@CorvidCrone As a former technical writer, I approve this message!

[davemwilburn@infosec.exchange]

@CorvidCrone

Sorry, best I can do is an excruciating and meandering 29-minute long YouTube video sponsored by Nord VPN.

[dkf@cyberplace.social]

@CorvidCrone I got an archive.org record of a blog post that links a badly-compressed youtube video of a talk that has a briefly skipped past slide with a sentence about the API you're interested in.

I'm surprised there's no sign "Beware of the Leopard".

(There are bits of LLVM's advanced features that feel like they're documented exactly like this. Maybe they improved it. I doubt it, but maybe...)

[pattycat@mastodon.social]

@CorvidCrone user manuals, service manuals I keep from the parts and equipment along with the start-up reports I collate next to the equipment I service and maintain

[ianbadcoe@peoplemaking.games]

@CorvidCrone And I certainly don't want to have to watch a half hour YouTube video that may or may not turn out to be for the same version...

[gourd@indiepocalypse.social]

@CorvidCrone unfortunately in the current state of things it's more likely you get a chatbot sent to you with a rice cooker *sigh*

[swade2569@mastodon.social]

@CorvidCrone No video on YT either, asking me to like share and subscribe, spending 3/4 of the time talking about and around the problem before giving a solution which is hardly a solution at all which they then link to another solution…… fuuuuuu