We're going to have to agree to disagree on this one. But let me give you all an example.
Wolfram Documentation on Mathematica is excellent in my humble opinion. Here is a function I use very often, convolve.
https://reference.wolfram.com/language/ref/Convolve.html
Notice how the interface is very well described, there are examples on how to use it, but there are no implementation details.
Re:On Apple's Piss-Poor Documentation
by justinclift on Saturday November 14, 2020 @09:07AM
(#25092358)
Your reference example includes lots of details, examples of usage including source, explanation of options, etc. :)
That's not an "easier to keep documentation up to date" type of thing ;), but is definitely an example of good documentation.
Unlike the Apple approach mentioned above. :( :( :(
That's NOT a "good" reason in any sense.
That's a terrible reason, which no-one in a team leader or above position should ever sign off on.