rust?

Posted Feb 27, 2025 14:53 UTC (Thu) by Wol (subscriber, #4433)
In reply to: rust? by amarao
Parent article: A change in maintenance for the kernel's DMA-mapping layer

Don't forget, writing good documentation is a skill. And good coders are often crap documenters.

Apologies for getting on my high horse here - but has anybody noticed what happened to kernel raid wiki? It was aimed at USERS - people running raid, people who didn't know what raid was, people who wanted to set up a system. It quite deliberately did NOT attempt to duplicate the official kernel documentation.

So someone came along, archived it with a big notice saying "this is obsolete, refer to the official kernel documentation if you need anything". WTF!!!

For the target readers of the wiki, the official kernel documentation is probably written in something worse than double dutch !!!

And this is a major problem with modern documentation - it usually completely ignores the user and is written BY experts, FOR experts. Which is why most user documentation is a case of the blind leading the blind. (My new TV is a case in point - it's a complicated computer, and the user documentation consists pretty much entirely of "plug the power lead here, the network cable there, and the aerial this other place". There's loads of fancy stuff we don't have a clue how to use!)

PLEASE KERNEL GUYS - *DON'T* piss off users who are trying to teach people how to USE your software. Without users, there's no point you writing it !!!

Cheers,

Wol

rust?

Posted Feb 28, 2025 8:48 UTC (Fri) by taladar (subscriber, #68407) [Link] (3 responses)

To be fair writing documentation for a beginner as an expert is genuinely hard since the thought processes can be entirely different and you don't even consciously think about many of the things other people might not know that you have known for decades.

However having expert documentation for experts would be a good first step at least to allow someone else with a different skill set to write documentation for users. Having no documentation at all requires both the skill set to read undocumented code (which is much harder than writing undocumented code) and the skill set to write good documentation in the same person.

rust?

Posted Feb 28, 2025 14:06 UTC (Fri) by mathstuf (subscriber, #69389) [Link]

Agreed. One strategy I use is to at least get my brain dump down somewhere as a seed. Then try to prod others to go through the steps of the process via the docs and to involve me in review of the results. Any missed steps (because they're "implicit" to me) get written down for posterity.

rust?

Posted Feb 28, 2025 15:44 UTC (Fri) by Wol (subscriber, #4433) [Link] (1 responses)

> However having expert documentation for experts would be a good first step at least to allow someone else with a different skill set to write documentation for users.

Actually no. From the user's PoV, (a) that documentation is probably written in double dutch, and (b) addresses completely the wrong problem, anyway. If I want to learn to be a chauffeur, why on earth do I want a detailed schematic of an Internal Combustion Engine? (Yes, knowing that schematic might be useful, but it's completely orthogonal to the problem at hand.)

The gap between the maker's understanding, and the user's understanding, of any product grows wider much faster than I suspect many of us here realise. A good maker is curious about what they're making. A user usually cares very little beyond "how do I get this to work" (because they don't have time for much more). Assuming the documentation will be cross-comprehensible between the two groups is asking for problems ...

Cheers,
Wol

rust?

Posted Feb 28, 2025 18:34 UTC (Fri) by draco (subscriber, #1792) [Link]

Umm, reread the quoted text again.

It's not saying that "expert documenting for experts, the end" = "user documentation, though of lower quality"

It's saying that "expert that's bad at user documentation documenting for experts that can't figure it out from raw code" leads to "experts that are good at user documentation creating decent user documentation" with higher probability than the alternative.

Now, if you're saying that documenting how it works instead of intended behavior for end users doesn't necessarily help describe the intended behavior, that's a fair statement, but I'd argue that if you don't have both, you don't have adequate expert documentation either.