*gently grabs the cheeks of all programmers to stare deeply into their eyes*
-
*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.
-
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.
I would also submit that •until• you've written the manual, your •software• isn't finished, bc documenting the product will surface problems you can find in no other way....
-
*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 Yes. Yes, and Yes.
Though I'm glad community forums are a thing now that customer service doesn't actually exist.
-
*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 Programmer replies: "I'd like to provide one but the Product Manager shot that idea down.
" -
@CorvidCrone Programmer replies: "I'd like to provide one but the Product Manager shot that idea down.
"Getting in my car, going to the hairdresser, getting the Karen cut, and then driving to your product manager
-
@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. -
@Steveg58 that's a lot of acronyms I don't know
-
*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 I have long wished I were that technical writer.
Hire me.
-
Getting in my car, going to the hairdresser, getting the Karen cut, and then driving to your product manager
@CorvidCrone *dying here*
-
*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.
Can we please also ensure that this manual doesn’t assume I already know what I’m doing? If that were so, I wouldn’t need the 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.
Two things I learned in an indexing class — be, an index is copyrightable independent of the work; and two, a work doesn’t need to be very complicated before two professional indexers might come up with strikingly different indexes.
-
@CorvidCrone Do you need a Linux distro? https://mxlinux.org/manuals/
This is the second Linux distro I've been offered.
Why? How does that address the issue of software I must use for work not having a tech manual?
-
@CorvidCrone I have long wished I were that technical writer.
Hire me.
-
I approve
-
*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 "...but ChatGPT can summarize it for y—"
-
*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 am writing one, mostly out of sheer, pent-up rage at the Cool Kids.
Give people a working 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 Ah, the good old days, when you were only a real tech writer if you could straightarm your documentation
