9 ms·

Better: We need to stop using undocumented proprietary systems like macOS.

mvdwoord 9y ago
In contrast to undocumented free (open) systems? Documentation is an issue irrespective of prorietariness(??!) of a system. 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.)
- ben0x539 9y ago
  I mean, I'm not the target audience and I don't have the attachment to OSX as a platform, but if I was gonna expend the energy to document a thing, I'd hope it goes towards a good cause and isn't just free labor for like the richest corp I can think of from the top of my head.
  - ewjordan 9y ago
    Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). Impact is a big factor in how useful an activity is, even if it's tied to a big company.
    - em3rgent0rdr 9y ago
      > "Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux" 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.
      - sooheon 9y ago
        Not sure that I agree with the second proposition. I'm pretty sure vastly more people choose to use iOS and macOS than free systems.
        em3rgent0rdr 9y ago
        But more people will choose to use free systems if they get better documentation (that is tailored to average folk, not computer enthusiasts).
    - geofft 9y ago
      > Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). 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.
      - pjmlp 9y ago
        Android is only about Java. 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.
        geofft 9y ago
        That depends if you're talking about user docs or developer docs. I'm saying that we should document wpa_supplicant as user documentation: if there are caveats like, oh, "Android 5.1 and lower can't connect to TLSv1.2-only PEAP or EAP-TLS networks," that should be documented for end users but is irrelevant for devs since wpa_supplicant isn't accessible to the application at all. It's not a library/API, it's a system daemon. (But maybe I missed the point and we're specifically talking about developer documentation here?)
        pjmlp 9y ago
        I am speaking about developer documentation. 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.
    - pjmlp 9y ago
      OS X devs are also devs.
  - Karunamon 9y ago
    Maybe, sometimes, some of us just want to make a thing we use better rather than attaching grandiose moral judgements to the political status of a piece of fucking code.
- eikenberry 9y ago
  There is no undocumented open source software, the documentation is just in a technical language. This is why learning to program is important, as it also means learning how to read the documentation. 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.
  - lucaspiller 9y ago
    I don't disagree with you, but I feel this misses the point about technical documentation. Code tells you how something works, but it doesn't tell you why it works that way - which is often just as important. 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.
    - em3rgent0rdr 9y ago
      Well then maybe we all should write enough comments and tests to fully document behavior.
  - jacobolus 9y ago
    Code is the end result of a thinking / problem solving process, not the process itself. If I implement a mathematical formula in code, the “documentation” is the academic paper where the formula is described and proved, and the whole context of textbooks and other papers where the relevant terms are defined and abstractions are constructed, not the handful of lines of abstract arithmetic on one-letter variable names in the code. If I throw away the paper, the code doesn’t suddenly become self-documenting. 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.
    - dungle6 9y ago
      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.
- type0 9y ago
  > In contrast to undocumented free (open) systems? There's choice so you don't have to use those - https://www.freebsd.org/doc/handbook/ https://www.freebsd.org/doc/handbook/
- user5994461 9y ago
  > In contrast to undocumented free (open) systems? Documentation is an issue irrespective of prorietariness(??!) of a system. 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.
- stuntkite 9y ago
  I dunno, they might be strapped for resources. Maybe they could hire a documentation team with all that Apple Music revenue. 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.
- zokier 9y ago
  Straight from the article: > Most open source projects are proud to have user documentation which is an order of magnitude better than anything provided by Apple for macOS.
- adgasf 9y ago
  It's much easier to document things when you can dive into the source-code.
- cbsmith 9y ago
  At least with the free software, you can hope to accurately document it.
LeoPanthera 9y ago
And use what? Windows spies on you and they call it a feature. Linux is a great server OS but a really terrible choice on the desktop. I'm not convinced that free software documentation is any better, either. macOS is the best desktop OS going, for the moment.
- em3rgent0rdr 9y ago
  > "but a really terrible choice on the desktop" This is a very subjective claim. Maybe a long long time ago you could say this, but not the case today. > "not convinced that free software documentation is any better" That's beside the point. If that were true, that is an argument for focusing a community effort at improving documentation for a free desktop. And actually with linux the problem is not as much a lack of documentation, but rather that the documentation is a little overwhelming, because it is just too specific or technical. (ever typed "man" something in a terminal?)
  - taurath 9y ago
    I shouldn't have to go to terminal to edit a conf file to make audio or video work. I have every single time I have tried Linux on the desktop. It does not work out of the box. You must know how to use terminal and edit Byzantine configurations, and read Linux forum posts from 2005 to make basic functionality work. It's my "subjective" opinion, but after 5+ hours troubleshooting and configuring as a power user who does know how to edit conf files I wouldn't recommend it to anyone.
    - oliwarner 9y ago
      That's it though, it very often does just work. Without vendor support and with barely any investment from manufacturers, the Linux community is still pushing on to get things to a point where your dog could install it. Your experience is an anomaly they're trying hard to eradicate.
      - taurath 9y ago
        I understand that, and have tried again nearly every year for the past 15, using the most "user friendly" distro I can find each time.
camillomiller 9y ago
Or maybe abandon strictly ideological and polarizing standpoints, accepting that most people are productive in different ways than our own, and conceding that not giving a damn about distros, dependencies and command line interaction doesn't make you a evil operator of the IT Satan?
hoorayimhelping 9y ago
Best: We need to stop making our preference on software an ethical issue and accept that proprietary software isn't bad just because it's not free.
- peatmoss 9y ago
  I'd posit that ethical reasons are a great basis to choose software. You either support the values that your software espouses or you don't. There isn't a correct answer there. Stallman has a "Why Open Source Misses the Point" article that I find pretty compelling. It suggests you should support Free Software because it's the right ethical thing to do, not because of the many instrumental utility arguments of the Open Source movement. He calls out specifically the notion that Open Source is intrinsically higher quality than commercial software. Indeed there are many high quality, well-functioning commercial bits of software out there. So, either the ethos of Free Software appeals to you, and you should choose it regardless of whether it is the highest quality, or you don't, in which case the function of the software should be your guide. I personally find the ethical argument compelling, and so often do forego "better" software in favor or freer software.
- skrebbel 9y ago
  I'd posit that ethical reasons may be the best reasons to do anything at all. Of course, the debate on how unethical using non-free software is has been going on for decades and both sides have reasonable arguments. Also, we're all people and hypocrites by definition. I do stuff that's against my fundamental morals every day (eg go to the cinema instead of save a life with the same money). Similarly I think I agree with the Stallmans of this world but I use Windows anyway. But still, "let's not let ethics get in the way of making choices" isn't the best argument I've ever read on HN :-)

In contrast to undocumented free (open) systems? Documentation is an issue irrespective of prorietariness(??!) of a system. 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.)

ben0x539 9y ago
I mean, I'm not the target audience and I don't have the attachment to OSX as a platform, but if I was gonna expend the energy to document a thing, I'd hope it goes towards a good cause and isn't just free labor for like the richest corp I can think of from the top of my head.
- ewjordan 9y ago
  Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). Impact is a big factor in how useful an activity is, even if it's tied to a big company.
  - em3rgent0rdr 9y ago
    > "Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux" 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.
    - sooheon 9y ago
      Not sure that I agree with the second proposition. I'm pretty sure vastly more people choose to use iOS and macOS than free systems.
      - em3rgent0rdr 9y ago
        But more people will choose to use free systems if they get better documentation (that is tailored to average folk, not computer enthusiasts).
  - geofft 9y ago
    > Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). 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.
    - pjmlp 9y ago
      Android is only about Java. 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.
      - geofft 9y ago
        That depends if you're talking about user docs or developer docs. I'm saying that we should document wpa_supplicant as user documentation: if there are caveats like, oh, "Android 5.1 and lower can't connect to TLSv1.2-only PEAP or EAP-TLS networks," that should be documented for end users but is irrelevant for devs since wpa_supplicant isn't accessible to the application at all. It's not a library/API, it's a system daemon. (But maybe I missed the point and we're specifically talking about developer documentation here?)
        pjmlp 9y ago
        I am speaking about developer documentation. 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.
  - pjmlp 9y ago
    OS X devs are also devs.
- Karunamon 9y ago
  Maybe, sometimes, some of us just want to make a thing we use better rather than attaching grandiose moral judgements to the political status of a piece of fucking code.
eikenberry 9y ago
There is no undocumented open source software, the documentation is just in a technical language. This is why learning to program is important, as it also means learning how to read the documentation. 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.
- lucaspiller 9y ago
  I don't disagree with you, but I feel this misses the point about technical documentation. Code tells you how something works, but it doesn't tell you why it works that way - which is often just as important. 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.
  - em3rgent0rdr 9y ago
    Well then maybe we all should write enough comments and tests to fully document behavior.
- jacobolus 9y ago
  Code is the end result of a thinking / problem solving process, not the process itself. If I implement a mathematical formula in code, the “documentation” is the academic paper where the formula is described and proved, and the whole context of textbooks and other papers where the relevant terms are defined and abstractions are constructed, not the handful of lines of abstract arithmetic on one-letter variable names in the code. If I throw away the paper, the code doesn’t suddenly become self-documenting. 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.
  - dungle6 9y ago
    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.
type0 9y ago
> In contrast to undocumented free (open) systems? There's choice so you don't have to use those - https://www.freebsd.org/doc/handbook/ https://www.freebsd.org/doc/handbook/
user5994461 9y ago
> In contrast to undocumented free (open) systems? Documentation is an issue irrespective of prorietariness(??!) of a system. 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.
stuntkite 9y ago
I dunno, they might be strapped for resources. Maybe they could hire a documentation team with all that Apple Music revenue. 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.
zokier 9y ago
Straight from the article: > Most open source projects are proud to have user documentation which is an order of magnitude better than anything provided by Apple for macOS.
adgasf 9y ago
It's much easier to document things when you can dive into the source-code.
cbsmith 9y ago
At least with the free software, you can hope to accurately document it.

LeoPanthera 9y ago

And use what? Windows spies on you and they call it a feature. Linux is a great server OS but a really terrible choice on the desktop. I'm not convinced that free software documentation is any better, either. macOS is the best desktop OS going, for the moment.

em3rgent0rdr 9y ago
> "but a really terrible choice on the desktop" This is a very subjective claim. Maybe a long long time ago you could say this, but not the case today. > "not convinced that free software documentation is any better" That's beside the point. If that were true, that is an argument for focusing a community effort at improving documentation for a free desktop. And actually with linux the problem is not as much a lack of documentation, but rather that the documentation is a little overwhelming, because it is just too specific or technical. (ever typed "man" something in a terminal?)
- taurath 9y ago
  I shouldn't have to go to terminal to edit a conf file to make audio or video work. I have every single time I have tried Linux on the desktop. It does not work out of the box. You must know how to use terminal and edit Byzantine configurations, and read Linux forum posts from 2005 to make basic functionality work. It's my "subjective" opinion, but after 5+ hours troubleshooting and configuring as a power user who does know how to edit conf files I wouldn't recommend it to anyone.
  - oliwarner 9y ago
    That's it though, it very often does just work. Without vendor support and with barely any investment from manufacturers, the Linux community is still pushing on to get things to a point where your dog could install it. Your experience is an anomaly they're trying hard to eradicate.
    - taurath 9y ago
      I understand that, and have tried again nearly every year for the past 15, using the most "user friendly" distro I can find each time.

camillomiller 9y ago

Or maybe abandon strictly ideological and polarizing standpoints, accepting that most people are productive in different ways than our own, and conceding that not giving a damn about distros, dependencies and command line interaction doesn't make you a evil operator of the IT Satan?

hoorayimhelping 9y ago

Best: We need to stop making our preference on software an ethical issue and accept that proprietary software isn't bad just because it's not free.

peatmoss 9y ago
I'd posit that ethical reasons are a great basis to choose software. You either support the values that your software espouses or you don't. There isn't a correct answer there. Stallman has a "Why Open Source Misses the Point" article that I find pretty compelling. It suggests you should support Free Software because it's the right ethical thing to do, not because of the many instrumental utility arguments of the Open Source movement. He calls out specifically the notion that Open Source is intrinsically higher quality than commercial software. Indeed there are many high quality, well-functioning commercial bits of software out there. So, either the ethos of Free Software appeals to you, and you should choose it regardless of whether it is the highest quality, or you don't, in which case the function of the software should be your guide. I personally find the ethical argument compelling, and so often do forego "better" software in favor or freer software.
skrebbel 9y ago
I'd posit that ethical reasons may be the best reasons to do anything at all. Of course, the debate on how unethical using non-free software is has been going on for decades and both sides have reasonable arguments. Also, we're all people and hypocrites by definition. I do stuff that's against my fundamental morals every day (eg go to the cinema instead of save a life with the same money). Similarly I think I agree with the Stallmans of this world but I use Windows anyway. But still, "let's not let ethics get in the way of making choices" isn't the best argument I've ever read on HN :-)