*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 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? -
*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 Ohhhh so so SO same!
-
*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 also not just a pile of doc comments rendered to HTML with zero context about how they fit into any workflow!
-
*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
My rice cooker also came with a helpdesk that I could contact to discuss problems not addressed in the manual, and the opportunity to order replacement parts. Software has a lot to learn from rice cookers! -
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 Sorry, thought it was more general and happen to be very grateful to my distro's 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.
The beginning of the end came when they started replacing man pages with GNU info files. Or maybe when they stopped creating GNU info files you could generate man pages from, and gave you man pages with scraps telling you to look in the info files.
-
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.
Oh interesting. A depth of knowledge of the tech of which I was unaware! TIL!
(I was introduced to the term "concordance" by the old #StarTrek Concordance originally produced by Bjo Trimble.
I just learned that there was a professionally published version, but I have the original, mimeographed one. Oddly, it didn't list guest actors, or the eps they appeared in. I put this together myself, from old TV Guide listings. It's two typed pages added in.
