*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.
@CorvidCrone A series of promotional learning videos, gotcha. Coming right up
-
@CorvidCrone not a bloody video. Honestly the UNIX man pages had the correct paradigm.
@chrisgerhard @CorvidCrone this, plus the very nice info pages for more structured details. Preferably read in #emacs, but there are plenty alternatives.
-
*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 GIVE ME MAN PAGES OR GIVE ME DEATH
-
*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 the ZX81 BASIC manual is my role model
-
@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 I remember when all tech manuals, and really, it was all of them, had an ASCII chart in the appendices
-
*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 learned my programming skills with books listing all instructions in ALPHABETICAL order with explanations.
I just went and read it all from A to Z. And then I knew how the language works. -
*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 so much this, for tech tools too. The datadog docs are all marketing crap and installation guides with very little actual information, for example. https://diataxis.fr/
-
*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 preach!
-
*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.
If this happens to be the sole surviving text of our civilization it will leave a good deal of room for interpretive detail.
Though for the most part they'll just label it as obscure religious poetry, much as they did for a century or so with the commercial bill of lading figurines that turned out to be the actual origins of the alphabet, on a closer view.
-
If this happens to be the sole surviving text of our civilization it will leave a good deal of room for interpretive detail.
Though for the most part they'll just label it as obscure religious poetry, much as they did for a century or so with the commercial bill of lading figurines that turned out to be the actual origins of the alphabet, on a closer view.
@glc I would be honored if one of my social media posts became the sole surviving text of our civilization.
Honored and horrified.
-
@glc I would be honored if one of my social media posts became the sole surviving text of our civilization.
Honored and horrified.
-
This is, in principle, how things should work.
This, of course, depends on the documentation writer being a competent communicator. Which, in the tech world certainly, is by no means a given.
The above is also true of websites.
But figuring out what the writer called the thing, and where they put it....
This can be a challenge.
(To be clear: hard agree.)
-
Oh, that's very good! Yes, that definitely seems like that would be the software equivalent of "measure twice, cut once."
Much easier to write the software when you know ahead of time exactly what you're trying to do.
Probably not much into the whole "vibe coding" thing, I'm guessing? (Runs away & hides behind a chair
) -
@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 Story time!
When I started a new job in the IT department of my company, I got sent for a week of training in the US. I got back with a brain full of new information and skills.
A few weeks later, I arrive at my desk, and someone is apparently using it for storage -- there are a dozen extremely heavy boxes, on my desk, on my filing cabinet, on the floor...
My mentor stops by, says "Oh, good. You got the manuals I ordered."
AIX, DB2, ADSM, CMOD, and others...
When I asked where I was supposed to put them, and how I was supposed to organize them, he said "Oh, I think they're already indexed by weight."
I actually read them. All of them.
-
*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 @jackbrewster This made me happy to read.
-
*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 is a big part of what i like about gnu software.
-
*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 anybody who worked with DEC manual/docsets for software will second this ...
-
@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
@Fragarach @CorvidCrone
Yes! A well authored index is much more that a printed replacement for search. It rewards browsing as much as lookup.One full pass through a good index give you an idea of what a book/paper contains and confidence that you can go back to the index to refresh your memory.
It can even be funny — like Kimbote’s index to ‘Pale Fire’
This seems ok:
https://www.litcharts.com/lit/pale-fire/the-index -
*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 as a programmer I want ~~to be grabbed by the cheeks~~ such manuals too.
-
@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 Microsoft C 7 (IIRC) came in a box a couple of feet long filled with books (a complete set of documentation for Windows development). And a few floppy disks tacked on at the end.
