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

[zl2tod@mastodon.online]

@CorvidCrone

With an overview, a functional description, and examples.

[firesphere@cloudisland.nz]

@zl2tod @CorvidCrone Best I can do is a video 🤮

[elala@nrw.social]

@CorvidCrone

[antimu0n@furry.engineer]

@Kay @CorvidCrone
you can update a PDF
you can update an ebook

[apples_and_pears@mastodon.world]

@CorvidCrone That's something I loved about DEC their manuals were actually helpful! Further they wrote in depth about each piece of hardware from the customer's POV and published it, freely giving copies to customers, and potential customers.

People learned what DEC hardware/software could do. Today people ask an AI to do "something.

If you want to be useful you have to know what is happening and how it's being done.

[follpvosten@karp.lol]

@CorvidCrone one more reason I like emacs

[chrisgerhard@mastodon.green]

@CorvidCrone not a bloody video. Honestly the UNIX man pages had the correct paradigm.

[gentlemantech@cyberplace.social]

@CorvidCrone not only this, but I want that manual to accurately describe the actual interface (UI or API) that your software presents.

Google GCP team, looking at you, you collection of malicious monkeys. Your documentation is *always* inaccurate. I always have to write a test iteration to discover what the permission scopes *really* are, and what actions they *really* allow. I have learned to never trust your docs, and it’s painful.

[starkrg@myside-yourside.net]

@CorvidCrone If you can't describe how to do something with text and have to resort to video links that might disappear in a couple of years, then you've made whatever it is *far* too difficult. No goddamned video tutorials that can't be easily referenced.

[robinsyl@meow.social]

@CorvidCrone DaVinci Resolve comes with a four thousand page manual

[gottox@chaos.social]

@CorvidCrone just give me a few comments in the header file, that's all I want!

[markix@blahaj.zone]

@CorvidCrone@kolektiva.social Ardour has a 119 chapter manual and it's so peak ​​

[juliarez@chaos.social]

@CorvidCrone

Testify!

The two best tech manuals I can think of were the service docs for the BBC micro and the Philips KT3 television chassis.

Modulo the early O'Reilly books, Droms & Lemon, and perhaps the Continuous Delivery book, everything else has been a bit awful.

[jandi@mastodon.social]

@CorvidCrone Do you need a Linux distro? https://mxlinux.org/manuals/

[fbarton@infosec.exchange]

@CorvidCrone Can I add one more qualifier please?

I want it to be accurate!

I can't start to count the number of "fully documented" APIs that I've dealt with where I end up sending in corrections because the documentation is missing critical information

[jeffbronks@c.im]

@JuliaRez @CorvidCrone
BBC Micro docs in general were superb. Partly what inspired me to become a Tech Author.

##bbcmicro #techwriting

[jeffbronks@c.im]

@CorvidCrone
And not a video.

[chloeraccoon@mastodonapp.uk]

@apples_and_pears @CorvidCrone dec manuals did come with the risk of the wall of documentation falling on you @majenko @baljemmett

[furball@tiggi.es]

@CorvidCrone @ahto If you need help just join the discord. Idk what the prob is.

[fragarach@social.vivaldi.net]

@CorvidCrone
Once upon a time I worked for a European electronics company. My bit was a specific area of medical software. They employed a team of technical writers for the user manuals. I didn't appreciate at first just how good the manuals were until I was training a physician with whom I had no common language. In the manual, Chapter 8, section 33.5.8 was exactly the same point in the workflow, explaining the objective of what I wanted to demonstrate.
And the index was an absolute joy to use.

They've probably moved on to using an LLM to write them now