*gently grabs the cheeks of all programmers to stare deeply into their eyes*
-
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.
@JuliaRez @CorvidCrone
BBC Micro docs in general were superb. Partly what inspired me to become a Tech Author. -
*gently grabs the cheeks of all programmers to stare deeply into their eyes*
All I want is a dry tech manual. A boring, well indexed manual that defines every function. Not a chatbot. Not a training. Not a million "articles" that I have to search through. Not a "community forum".
My rice cooker came with one. I want one for every piece of software I have to interact with.
Go get yourself a technical writer if necessary.
I. Want. An. Instructional. Manual.
@CorvidCrone
And not a video. -
@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.
@apples_and_pears @CorvidCrone dec manuals did come with the risk of the wall of documentation falling on you
@majenko @baljemmett -
*gently grabs the cheeks of all programmers to stare deeply into their eyes*
All I want is a dry tech manual. A boring, well indexed manual that defines every function. Not a chatbot. Not a training. Not a million "articles" that I have to search through. Not a "community forum".
My rice cooker came with one. I want one for every piece of software I have to interact with.
Go get yourself a technical writer if necessary.
I. Want. An. Instructional. Manual.
@CorvidCrone @ahto If you need help just join the discord. Idk what the prob is.
-
*gently grabs the cheeks of all programmers to stare deeply into their eyes*
All I want is a dry tech manual. A boring, well indexed manual that defines every function. Not a chatbot. Not a training. Not a million "articles" that I have to search through. Not a "community forum".
My rice cooker came with one. I want one for every piece of software I have to interact with.
Go get yourself a technical writer if necessary.
I. Want. An. Instructional. Manual.
@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
-
@JuliaRez @CorvidCrone
BBC Micro docs in general were superb. Partly what inspired me to become a Tech Author.Right? It's been a bit of a while, but you could read the (quite thin) service book, and feel like you could design a reasonable 6502 system on the back of an envelope _and_ be confident that you could fix all the common faults you'd come across.
Books like that should be inspiring rather than distressing. 'I've suffered, and I'm writing this so you don't have to' over 'I've suffered, and now you must, too'.
-
@CorvidCrone @ahto If you need help just join the discord. Idk what the prob is.
@Furball @CorvidCrone @ahto
I hope that's ironic.Discord is an unindexed hole where information gleaned by the communities the company offloaded support responsibilities on to goes to die. I am less likely to use a product or service if yhe only way you find out about it is the discord.
Haxe, a programming language i love is abouttyo release version 5. I can't find any information about the release because all announcements, changelogs and info are inside their discord. Might as well put it on facebook. -
@apples_and_pears @CorvidCrone dec manuals did come with the risk of the wall of documentation falling on you
@majenko @baljemmett@chloeraccoon @apples_and_pears @CorvidCrone @baljemmett You need DEC document EK-W4LLS-UG - How to extract human from document collapse
-
@chloeraccoon @apples_and_pears @CorvidCrone @baljemmett You need DEC document EK-W4LLS-UG - How to extract human from document collapse
@majenko @apples_and_pears @CorvidCrone @baljemmett Don't forget the 600 page binder... "How to locate and deal with bugs"
-
*gently grabs the cheeks of all programmers to stare deeply into their eyes*
All I want is a dry tech manual. A boring, well indexed manual that defines every function. Not a chatbot. Not a training. Not a million "articles" that I have to search through. Not a "community forum".
My rice cooker came with one. I want one for every piece of software I have to interact with.
Go get yourself a technical writer if necessary.
I. Want. An. Instructional. Manual.
@CorvidCrone that would mean the software would have to be correct, and they couldnt' constantly change everything.
-
Right? It's been a bit of a while, but you could read the (quite thin) service book, and feel like you could design a reasonable 6502 system on the back of an envelope _and_ be confident that you could fix all the common faults you'd come across.
Books like that should be inspiring rather than distressing. 'I've suffered, and I'm writing this so you don't have to' over 'I've suffered, and now you must, too'.
@JuliaRez @CorvidCrone
Yeah. The long version of my reply is "... to become a hardware engineer and then a tech author". The Beeb was the perfect blend of both. -
@Kay @CorvidCrone If bug fixes break functionality in a way that makes a rewrite of the instructional manual necessary, that's not ideal. Actually for updates that's hardly ideal either.
Also if you introduce new features along the way, why wouldn't you write instructions on how to actually use those? -
@CorvidCrone not a bloody video. Honestly the UNIX man pages had the correct paradigm.
@chrisgerhard @CorvidCrone A video can be a useful addition for some people to better understand something, but this should be always in this order: 1. Good manual, 2. Good tutorials, 3. something and anything else. (Those should also be up to date with possible older versions available too, if feasible, in my honest opinion.)
-
*gently grabs the cheeks of all programmers to stare deeply into their eyes*
All I want is a dry tech manual. A boring, well indexed manual that defines every function. Not a chatbot. Not a training. Not a million "articles" that I have to search through. Not a "community forum".
My rice cooker came with one. I want one for every piece of software I have to interact with.
Go get yourself a technical writer if necessary.
I. Want. An. Instructional. Manual.
-
*gently grabs the cheeks of all programmers to stare deeply into their eyes*
All I want is a dry tech manual. A boring, well indexed manual that defines every function. Not a chatbot. Not a training. Not a million "articles" that I have to search through. Not a "community forum".
My rice cooker came with one. I want one for every piece of software I have to interact with.
Go get yourself a technical writer if necessary.
I. Want. An. Instructional. Manual.
@CorvidCrone
No manual, no #RTFM! -
@majenko @apples_and_pears @CorvidCrone @baljemmett Don't forget the 600 page binder... "How to locate and deal with bugs"
@chloeraccoon @majenko @CorvidCrone @baljemmett Documentation can be overdone. It's more likely to be underdone and scattered here there and somewhere - if I could only remember where.
-
*gently grabs the cheeks of all programmers to stare deeply into their eyes*
All I want is a dry tech manual. A boring, well indexed manual that defines every function. Not a chatbot. Not a training. Not a million "articles" that I have to search through. Not a "community forum".
My rice cooker came with one. I want one for every piece of software I have to interact with.
Go get yourself a technical writer if necessary.
I. Want. An. Instructional. Manual.
I don't use it often, but when I do, I am reminded of what a glory & a wonder is the very thorough index in The Joy of Cooking.
I'm willing to bet that index took as long to construct as the entire rest of the book, but for my money, it's entirely worth it.
-
@chloeraccoon @majenko @CorvidCrone @baljemmett Documentation can be overdone. It's more likely to be underdone and scattered here there and somewhere - if I could only remember where.
@apples_and_pears @majenko @CorvidCrone @baljemmett Majenko had the classic one of those issues a few months ago. Looking up how to do something he was sure he had done before, and found a post telling him what to do. Written by Majenko...
-
@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
I had the great good fortune to have a hand in composing the manual for UNICOS, the variant of UNIX used on Cray computers, back in the day.
That experience informs •every• bit of writing I've done since, especially on the web.
-
*gently grabs the cheeks of all programmers to stare deeply into their eyes*
All I want is a dry tech manual. A boring, well indexed manual that defines every function. Not a chatbot. Not a training. Not a million "articles" that I have to search through. Not a "community forum".
My rice cooker came with one. I want one for every piece of software I have to interact with.
Go get yourself a technical writer if necessary.
I. Want. An. Instructional. Manual.
Saying this in complete agreement:
Most people have no concept of how much work goes into making a good manual. Done properly, it comprises about half the work of the entire project.
On the one hand, I understand the management/budget motive for eliminating that piece—especially since TFMs are famously rarely actually Red.*
OTOH—do you want your product to be actually f'g •useable•??
* Just noticed this ambiguity/typo. I think I'll leave it, since it actually reads plausibly.
