Comment by v1ne
13 hours ago
The trick about documentation is depth, not prose. You need context and understanding to write documentation "like in the old days". No amount of LLM trickery will free you from that. Once you have that source material, it's easy to re-shape it into an 80's/90's/00's doc format.
Negative example: I was looking into the German manual of my Canon EOS R5 II, and it is just fluff. Hundreds of pages, full of white space, telling me about features without actually explaining what they mean. Awful automatic translations. Their manuals used to be good (looking at my EOS 6D). But these days: oh boy.
My tooth brusher: Take the <Brand Name Product Name> and turn on <THE SUPERAWESOME MEGE POWER INNOVATIVE BEST IN THE WORLD> feature to experience <Brand Name Product Name> unique...
At that moment I felt sorry for this company, very sorry. How can you have so much disrespect for your customers? Does anyone in the physical world talk like this or do you marketing guys want to be talked to in such terms?
Brutal.
In that example they probably do view the median customer as a random peon, or not far from it…
And unless you are above the 99th percentile of the customerbase… that’d probably be a correct guess?
Heck they could directly write “You Peons!” and still probably retain most of their customer base… if the price to performance ratio was sufficiently better than the next best competitor.
Most people care so little about the refinement of anything else nowadays.
I doubt you have to be above 100 IQ to roll your eyes at obvious bullshit.
Author here. Another trick, I would argue, is consistency, hence the focus on style.
I also wrote on what I think makes docs beautiful, by the way! https://passo.uno/what-makes-docs-beautiful/
That is canon for ya, should have used INSERT_OTHER_MANUFACTURER_HERE$ /s
But if you look how much manuals get ignored by the customer, it doesn’t make sense to put work into them.
It is much better to let a YouTuber do it, by lending them the product and throw small amount of money against them.
Manuals are just there for legal or certifications requirements these days.
Yet they keep getting larger and less useful. It’s a matter of writing quality more than effort.
When was the last time you met a good technical writer? It’s a vanishing profession.
I dunno, depends on the subject/topic it seems to me. Most of the musical gear I buy nowadays come with manuals that are hundreds of pages long, including schematics, when to use what, tips and tricks, why things are the way they are and more. Even simple instruments like an analog mono bass comes with well-written schematics and lots of explanations. Even the manual for my mixer is 36 pages long, even though almost everything is self-explanatory, and besides that, it even has jokes and stuff in it too!