That is indeed the argument and I don't think it is necessarily a bad one.
Academic papers are both jargony and written in specialist notation and are not generally accessible to lay people without background in the field. I don't see how it is really much different.
Re:We need to document macOS
by eikenberry on Sunday August 13, 2017 @06:20PM
(#15005267)
As a firm believer in the old adage that programs are written for people to read, and only incidentally for the machine to execute, I don't buy into this reductionist argument. Code doesn't become self-documenting automatically, writing self-documenting code is one of those things you learn that makes you a good developer. If you throw away your documentation and then can't read the code, you've written bad code.
Re:We need to document macOS
by em3rgent0rdr on Sunday August 13, 2017 @01:47PM
(#15003960)
Good code can be understood just by reading it. That is practically impossible with binaries.
I think that's kind of jacobolus' point though.
(at the risk of speaking for someone else)...
jacobolus is saying that in both binary and source format, code is readable. It's just a matter of scale as to how readable each is.
Source is an abstraction of the code that is actually running, and documentation should be an abstraction of the source and how the running code works.
If you’re going to make such a reductionist definition of “documentation”, why not go all the way: every executable program is just a sequence of clear and simple instructions to the machine. The documentation of what each instruction does is right there in black and white. Why would you need anything else? All programs are documented.