*gently grabs the cheeks of all programmers to stare deeply into their eyes*
-
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.
-
*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.
How am I supposed to RTFM if they won't give me the F M?
-
How am I supposed to RTFM if they won't give me the F M?
@BlueDot exactly!
-
*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, a tech writer, want to WRITE the instructional manual for someone. Really.
Why should your users have a "help chatbot" jumping and swirling in the bottom corner of your screen while you type? -
@CorvidCrone I, a tech writer, want to WRITE the instructional manual for someone. Really.
Why should your users have a "help chatbot" jumping and swirling in the bottom corner of your screen while you type?@Rjayne_n and the chatbot always pops up over whatever you're looking at
-
*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 how I felt trying to get any sort of idea what the hell a "databricks" is
as far as I can tell it's some sort of marketing website that allegedly can do things with data but without some sort of training I don't think I'll ever really know.
-
@Rjayne_n and the chatbot always pops up over whatever you're looking at
@CorvidCrone Yes it does. Sigh.
Normally saying "hey are you looking for something?"... normally it's the button to turn it off.
-
@Kay Updates shouldn’t break the existing features. changing existing features should be rare, because it breaks learned behaviours. Having to update the manual might be friction enough to save us from ever changing UIs.
-
*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 manual should include pictures, like the toolbar icon to click, and images that make it plain where in the UI a feature is located.
-
*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.
Go get yourself a technical writer if necessary.
Oh, great. I "got" one. My bf is one.
But he's currently laid off, but not because of AI but because of outsourcing. -
*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 former technical writer, I approve this message!
-
*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.
Sorry, best I can do is an excruciating and meandering 29-minute long YouTube video sponsored by Nord VPN.
