*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 good old days 🥲
@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.
With an overview, a functional description, and examples.
@CorvidCrone That's something I loved about DEC their manuals were actually helpful! Further they wrote in depth about each piece of hardware from the customer's POV and published it, freely giving copies to customers, and potential customers.
People learned what DEC hardware/software could do. Today people ask an AI to do "something.
If you want to be useful you have to know what is happening and how it's being done.
<long indrawn breath> ooh sibling in science, I don't believe I've seen one of those in a very long time, possibly not since the summer of, hmmm, maybe '93
I miss them, too.
@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.
Testify!
The two best tech manuals I can think of were the service docs for the BBC micro and the Philips KT3 television chassis.
Modulo the early O'Reilly books, Droms & Lemon, and perhaps the Continuous Delivery book, everything else has been a bit awful.
@JuliaRez @CorvidCrone
BBC Micro docs in general were superb. Partly what inspired me to become a Tech Author.
Right? It's been a bit of a while, but you could read the (quite thin) service book, and feel like you could design a reasonable 6502 system on the back of an envelope _and_ be confident that you could fix all the common faults you'd come across.
Books like that should be inspiring rather than distressing. 'I've suffered, and I'm writing this so you don't have to' over 'I've suffered, and now you must, too'.
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 Can I add one more qualifier please?
I want it to be accurate!
I can't start to count the number of "fully documented" APIs that I've dealt with where I end up sending in corrections because the documentation is missing critical information
@Furball @CorvidCrone @ahto
I hope that's ironic.
Discord is an unindexed hole where information gleaned by the communities the company offloaded support responsibilities on to goes to die. I am less likely to use a product or service if yhe only way you find out about it is the discord.
Haxe, a programming language i love is abouttyo release version 5. I can't find any information about the release because all announcements, changelogs and info are inside their discord. Might as well put it on facebook.
@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 😬
I had the great good fortune to have a hand in composing the manual for UNICOS, the variant of UNIX used on Cray computers, back in the day.
That experience informs •every• bit of writing I've done since, especially on the web.
@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
Sorry,
Key Performance Indicator. Some calculated or measured number that is used to determine if an individual or department is performing well. Usually chosen for convenience to the measuring body not for actual relevance to the end result. Promotion and bonuses are often tied to KPI measures.
Source Lines Of Code. A very crude measure of programmer output but often used for KPIs. Ignores comments and is hard to calculate automatically. Poor code often generates higher SLOC counts than good code. Does not measure how well the code is explained by comments and documentation.
Source Lines Of Documentation. An unused crude, parallel measure of the amount of documentation attached to a software product.
Corvid Crone
nadja
The Doctor
DanCast
ferricoxide
Justin Derrick
Tim Ward ⭐🇪🇺🔶 #FBPE
pela0
zl2tod
Simon 🐮
Kay 
antimu0n 🤘 metal lynx ♿ 🏳️🌈🏳️⚧️
Paavi (ei se paavi)
Dave
Chloé Raccoon
Majenko
Luck Goddess 🌒🌕🌘 (They/She)
chrisgerhard
The Grue
kit
Gentleman Technologist
Donald Ball
StarkRG
Robin Syl 🌸
(1) Enno T. Boland
Emily 
stib
Julia Rez
Jeff Bronks
jandi
Frank Barton
Furball
Bloognoo
Fragarach
Cavyherd
Greg Lloyd
Steveg58
Binder
solo “claire” esta bien