*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.
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
-
*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 if you're worried that some users won't be able to read that manual — you should include a comic for them. no, really.
-
@CorvidCrone if you're worried that some users won't be able to read that manual — you should include a comic for them. no, really.
@fishidwardrobe I'm not worried. I know people don't read most of the stuff they are supposed to. Such is the life of compliance and risk management
-
@CorvidCrone I miss the time when software came with manuals fit for knocking out your manager in case he gave you shit for still reading through the War-and-Peace-sized manual
@dequbed @CorvidCrone Hard same!
-
@Kay @CorvidCrone
you can update a PDF
you can update an ebook@antimu0n @Kay @CorvidCrone Those have largely been replaced with thousands of shitty articles in knowledge bases running on Atlassian or Salesforce.
-
@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.
@GentlemanTech @CorvidCrone AWS and Cisco, also.
-
@sif @CorvidCrone The best documentation is what you sucker end users into writing for you. /s
-
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.
In which case, you should include •both• indexes (preferably integrated), to cover as many bases as possible.
Because, as comprehensive as an index might be, •users• will come up with questions that are not covered!
-
@dequbed @CorvidCrone Hard same!
@drwho @CorvidCrone honestly, the software was also pretty damn shite. I'm certainly not missing the quality of the software itself, but I am missing the quality of documentation that was generally expected.
-
@drwho @CorvidCrone honestly, the software was also pretty damn shite. I'm certainly not missing the quality of the software itself, but I am missing the quality of documentation that was generally expected.
@dequbed @CorvidCrone WordPerfect, Word, Turbo IDE, and, hell, EDIT.COM had their flaws, but they also were miles more usable and less troublesome than most user software these days.
-
@dequbed @CorvidCrone WordPerfect, Word, Turbo IDE, and, hell, EDIT.COM had their flaws, but they also were miles more usable and less troublesome than most user software these days.
@drwho @CorvidCrone maybe, I never used most of those too much. But old CAD and CAM software was *bad*. Simulation / scientific software even more so. Sure if your previous standard was batch processed hand punched FORTRAN they were all usable but a lot of companies really showed that they were trying out these newfangled GUIs for the first time and spend all their money on the shiny interface and none on fixing bugs.
-
In which case, you should include •both• indexes (preferably integrated), to cover as many bases as possible.
Because, as comprehensive as an index might be, •users• will come up with questions that are not covered!
Oddly, you can’t always integrate indexes, because they can be expressing different approaches of understanding. Which is why they are copyrightable: they bring something that can’t be mechanically extracted from the text.
If you keep putting everything in, you get to a concordance (old term) or full text search (new term) and now you’re requiring the reader to construct their approach to understanding.
-
*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
Would it be ok if it was all on discord or slack?
