*gently grabs the cheeks of all programmers to stare deeply into their eyes*
-
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.
-
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.
Ha, when concordances were manual there was a short list of works that got them — Bibles, Homer, Shakespeare — and Star Trek! TIL.
-
*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 80% of the time strongly dislike the interactive "tutorial" that pops up while I'm in the middle of intuiting how to do the desired function in the software
I would really rather have a manual where I can look it up if I run into problems
-
*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 This. And some yt-Videos are Not.A.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 While we're all here: we gotta knock off the cutesy error messages.
If i see another error message that's just a nerd reference im gonna [REDACTED]
-
*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 linux man pages: 🫥
-
@CorvidCrone This. And some yt-Videos are Not.A.Manual.
@maikek if I have to slide back and forth on a YouTube video to see the one specific thing I need, I will explode
-
@CorvidCrone While we're all here: we gotta knock off the cutesy error messages.
If i see another error message that's just a nerd reference im gonna [REDACTED]
We just wanna know what went wrong and how to fix it
how is this so hard?? -
Ha, when concordances were manual there was a short list of works that got them — Bibles, Homer, Shakespeare — and Star Trek! TIL.
I mean, in fairness, it was only like 20 pages. I imagine the Professional Version was bigger than that. But yeah!
Important Cultural Touchstones
! -
@maikek if I have to slide back and forth on a YouTube video to see the one specific thing I need, I will explode
@CorvidCrone people even add unnecessary filling to prolong their videos to the length of pay-worthiness ...
-
*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 don't have enough soapboxes to empathise fully with your post.
I'm a tech writer and (former?) programmer, with empathy.
-
*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 You are in good company.
I think, related to this, is that I want software to change more slowly. More contemplation. More thought. More pause. One new version per year, thought through with more intentionality.
-
@GentlemanTech @CorvidCrone AWS and Cisco, also.
@drwho @GentlemanTech @CorvidCrone AWS IAM docs are a trash fire. Half the examples just shrug and use wildcards. String matching, for access control primitives, because not even the insiders have accurate reference documentation.
