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

[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

[wordman@dice.camp]

@CorvidCrone I don't think it is programmers you need to convince of this.

[darkmatterzine@mastodon.social]

@CorvidCrone yes, this. I love a good manual. Contents, index and a good search function.
Hubby has been told over the years that one of the reasons he’s such a good programmer is that he notates his code as he goes so it’s easy for others to see what he’s done and, later, to modify it without causing a chain reaction.

[cyancqueak@dice.camp]

@dequbed @drwho @CorvidCrone pleasingly the ANSYS of 2007 came with a manual that told you everything that every function and setting did. Those were the days of the GUI mostly being a tool to write a text file for the computational bit.

[nlarson830@techhub.social]

@CorvidCrone

<whiny voice>
"Bbut instruction manuals are haaard."

Extra steps that are important:
1) Have that technical writer's work vetted by the people that wrote the software.
2) Bare minimum make the manual available as a PDF, ideally a printed on paper manual TOO!

[oldmankris@mastodon.xyz]

@gilesgoat @CorvidCrone I was so lucky in my first job: my cubicle was right next to all the shelves of VMS and other OS docs. Nice to browse through during the two-hour compile times.

[tusharhero@mathstodon.xyz]

@CorvidCrone GNU Info manuals are good

[tusharhero@mathstodon.xyz]

@resuna @CorvidCrone Info manuals are strictly superior to man pages though.

[resuna@ohai.social]

@tusharhero @CorvidCrone

More verbose, anyway. Harder to use as references. Like the difference between a document and a website.

[haui@mastodon.giftedmc.com]

@CorvidCrone
Most sane take on the fedi in a week.

[dequbed@mastodon.chaosfield.at]

@cyancqueak @drwho @CorvidCrone yeah, a bunch of software just uses GUIs for nicer setup of the batch processing pipeline. Those are all fine, turns out we have by now figured out batch processing
Biggest issue with batch processing is the very slow feedback cycle for errors, but that's solved by aiming for slower churn and more slack for unexpected errors and any work envionment that does that is better off for it anyway ^^