I welcome this initiative.
(Yes I know there are examples of documentation excellence to be found in some free/open systems. You can advocate their use whilst also having well documented macOs.)
Impact is a big factor in how useful an activity is, even if it's tied to a big company.
From a purely utilitarian perspective:
- The same amount of effort spent trying to document will result in more documentation being produced on a free system, since free systems are easier to document.
- The same amount of documentation produced will result in more benefit from end users for a free system, because more people will be able to use a free system.
Documentation effort towards Linux would help get that number up from nobody plus epsilon.
Also, at this point that's just not true because of Android. Most of the userspace is different from normal GNU/Linux distros, but not all: for instance, if your question is "how the heck am I supposed to connect to this WPA-Enterprise network," it's wpa_supplicant under the hood whether you're using Android's network dialog or GNOME's, and documenting wpa_supplicant's abilities and bugs helps Android users just as much as GNOME users.
The NDK APIs are quite constrained and only meant to be used for Java native methods, real time audio and high performance graphics.
Google can replace the kernel for anything else POSIX like, with the same set of NDK APIs.
Since Android 7, they have been locking down access to anything else not part of the official NDK APIs.
(But maybe I missed the point and we're specifically talking about developer documentation here?)
As for user documentation, any OEM is free to do whatever they feel like, so you don't have any guarantee how much of it is actually like AOSP.
Samsung is well known among Android devs for breaking AOSP compatibility.
Seriously, a company with the more GDP than entire nations should be able to do a better job at documenting than the Fedora team. Even if it is a loss leader.
There's choice so you don't have to use those - https://www.freebsd.org/doc/handbook/
I'm not being factious. We always say that documentation doesn't keep up and that the only real documentation is the code. Ultimately the only reliably documented software is free software.
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.
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.
(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.
To your actual point, what hampers free software more than anything imo is a lack of focus on usability. People buy Apple because, less now than a few yeara ago but still the vast majority of the time, it Just Works. People buy Creative Cloud for much the same reason, and Office 365, and whatever other proprietary products you care to name, because they mostly work reliably, and it's not hard to find help when they don't.
This is the standard free software needs to meet in order to compete. The reason it doesn't, I think, is because the economic incentive to do so is not there. That's not a problem I know how to solve, and I wish I did, because then I'd be able to advocate free software (and hardware!) for general use, as I would strongly prefer to do. As the matter stands now, though, I can't do so without critically damaging my credibility with those among whom I would so advocate.
That's a problem that needs to be solved. How does it become so?
I know. I've have had friends who I installed linux on their computer then call me in a few months describing some strange problem, probably related to a broken update, and then in a few months I cringe when I see them buying the latest Apple product but understand why. I worry they think less of free software after that experience.
Unless we start writing paragraphs of comments for every little five line function, there will still be a need for technical documentation outside of code.
> Most open source projects are proud to have user documentation which is an order of magnitude better than anything provided by Apple for macOS.
Windows and Android had much better documentation than Linux for a long time.
That is one of the major reason of why they are where they are nowadays.