News for hackers. Stuff that matters.
Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @04:55AM (#15002149)
Better: We need to stop using undocumented proprietary systems like macOS.
Re:We need to document macOS by mvdwoord on Sunday August 13, 2017 @05:04AM (#15002175)
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.)

Re:We need to document macOS by ben0x539 on Sunday August 13, 2017 @05:10AM (#15002188)
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.
Re:We need to document macOS by Karunamon on Sunday August 13, 2017 @04:31PM (#15004785)
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.
Re:We need to document macOS by ewjordan on Sunday August 13, 2017 @05:29AM (#15002231)
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.

Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @05:57AM (#15002294)
> "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.

Re:We need to document macOS by sooheon on Sunday August 13, 2017 @01:29PM (#15003867)
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.
Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @01:44PM (#15003947)
But more people will choose to use free systems if they get better documentation (that is tailored to average folk, not computer enthusiasts).
Re:We need to document macOS by geofft on Sunday August 13, 2017 @07:55AM (#15002556)
> 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.

Re:We need to document macOS by pjmlp on Sunday August 13, 2017 @02:50PM (#15004300)
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.

Re:We need to document macOS by geofft on Sunday August 13, 2017 @06:51PM (#15005419)
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?)

Re:We need to document macOS by pjmlp on Monday August 14, 2017 @02:37AM (#15006933)
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.

Re:We need to document macOS by pjmlp on Sunday August 13, 2017 @02:46PM (#15004274)
OS X devs are also devs.
Re:We need to document macOS by stuntkite on Sunday August 13, 2017 @06:03AM (#15002312)
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.

Re:We need to document macOS by type0 on Sunday August 13, 2017 @05:15AM (#15002200)
> In contrast to undocumented free (open) systems?

There's choice so you don't have to use those - https://www.freebsd.org/doc/handbook/

Re:We need to document macOS by eikenberry on Sunday August 13, 2017 @05:12AM (#15002196)
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.

Re:We need to document macOS by jacobolus on Sunday August 13, 2017 @05:47AM (#15002267)
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.

Re:We need to document macOS by dungle6 on Sunday August 13, 2017 @01:23PM (#15003830)
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.
Re:We need to document macOS by CaptSpify on Sunday August 13, 2017 @05:46PM (#15005138)
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.

Re:We need to document macOS by throwanem on Sunday August 13, 2017 @05:52AM (#15002276)
You're totally being factious in favor of free software. Not facetious, though, I agree.

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?

Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @02:01PM (#15004032)
> "I can't do so without critically damaging my credibility with those among whom I would so advocate."

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.

Re:We need to document macOS by throwanem on Sunday August 13, 2017 @02:02PM (#15004039)
They do, and justifiably so.
Re:We need to document macOS by yoz-y on Sunday August 13, 2017 @06:21AM (#15002345)
ElementaryOS seems to be going in the right direction. But I suppose the main "thing that works" is to have a team of people that actually enjoy making software usable by the masses rather than solving X for their own needs.
Re:We need to document macOS by throwanem on Sunday August 13, 2017 @11:08AM (#15003186)
That's a rare sort of intrinsic motivation, though, and tends not to last long in the face of frequent contact with users who, having their own situations to deal with, reasonably tend more often to complain about software that fails to make their lives easier than compliment that which does. That's where extrinsic motivation needs to come into play, but it's not much on offer in the context we're considering.
Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @07:15PM (#15005522)
maybe can get doc writers who care more about people rather than things...
Re:We need to document macOS by starsinspace on Sunday August 13, 2017 @06:55AM (#15002412)
Well, in that way, there's no undocumented proprietary software either. The documentation is just in an even more technical language, called machine code.
Re:We need to document macOS by pjmlp on Sunday August 13, 2017 @02:52PM (#15004307)
The documentation is available in books people are supposed to buy.
Re:We need to document macOS by lucaspiller on Sunday August 13, 2017 @05:43AM (#15002256)
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.

Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @02:03PM (#15004046)
Well then maybe we all should write enough comments and tests to fully document behavior.
Re:We need to document macOS by zokier on Sunday August 13, 2017 @06:24AM (#15002349)
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.

Re:We need to document macOS by user5994461 on Sunday August 13, 2017 @05:30AM (#15002232)
> 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.

Re:We need to document macOS by adgasf on Sunday August 13, 2017 @08:52AM (#15002706)
It's much easier to document things when you can dive into the source-code.
Re:We need to document macOS by cbsmith on Sunday August 13, 2017 @02:26PM (#15004167)
At least with the free software, you can hope to accurately document it.
Re:We need to document macOS by hoorayimhelping on Sunday August 13, 2017 @07:26AM (#15002483)
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.
Re:We need to document macOS by peatmoss on Sunday August 13, 2017 @10:35AM (#15003051)
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.

Re:We need to document macOS by skrebbel on Sunday August 13, 2017 @12:12PM (#15003440)
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 :-)

Re:We need to document macOS by camillomiller on Sunday August 13, 2017 @06:08AM (#15002325)
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?
Re:We need to document macOS by LeoPanthera on Sunday August 13, 2017 @05:29AM (#15002228)
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.

Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @05:40AM (#15002250)
> "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?)

Re:We need to document macOS by taurath on Sunday August 13, 2017 @06:01AM (#15002307)
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.
Re:We need to document macOS by sds2 on Sunday August 13, 2017 @08:29AM (#15002646)
> I shouldn't have to go to terminal to edit a conf file to make audio or video work.

I never needed to.

> It does not work out of the box.

It does.

> You must know how to use terminal and edit Byzantine configurations, and read Linux forum posts from 2005 to make basic functionality work.

What was your problem?

> 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.

You're lying, if you'd be a "power-user" then you wouldn't complain about manual text-based configuration.

Re:We need to document macOS by throwaway413 on Sunday August 13, 2017 @11:35AM (#15003305)
Seriously - I prefer text-based config via CLI
Re:We need to document macOS by oliwarner on Sunday August 13, 2017 @06:18AM (#15002339)
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.

Re:We need to document macOS by taurath on Sunday August 13, 2017 @07:03AM (#15002429)
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.
Re:We need to document macOS by oliwarner on Sunday August 13, 2017 @01:27PM (#15003859)
I don't mean to say that there aren't problems, just that they are fewer today than ever before.

It only takes a particularly new graphics card, or certain wireless chipset to give even battle-hardened users a novel and painful experience.

Re:We need to document macOS by Ezhik on Sunday August 13, 2017 @10:27AM (#15003025)
Apple devices are fine-tuned to run macOS. It doesn't make sense to compare a MacBook to some random Linux installation on incompatible hardware.

Buy one of those Developer Edition Dell laptops to even the field, and compare then.

Re:We need to document macOS by pjmlp on Sunday August 13, 2017 @02:53PM (#15004314)
They are almost impossible to buy in Germany.
Re:We need to document macOS by Nullabillity on Sunday August 13, 2017 @06:23AM (#15002348)
Audio has "just worked" for years now, thanks to PulseAudio. Video was a mess for a while, but now it will generally work great out of the box if you've got Intel or AMD graphics. Nvidia is still a mess, but Nouveau will work fine for non-gaming stuff.
Re:We need to document macOS by ZenoArrow on Sunday August 13, 2017 @10:59AM (#15003140)
> "Audio has "just worked" for years now, thanks to PulseAudio."

For your use cases perhaps, but it's not suitable for all use cases in the same way CoreAudio on OSX is. Music production is a key weak point, which is why JACK and PulseAudio are both required to have what CoreAudio offers out of the box.

Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @11:13PM (#15006396)
There are a few options to allow for Jack and PulseAudio to coexist: http://jackaudio.org/faq/pulseaudio_and_jack.html

There is a reason why there is both Jack and Pulse...they meet different needs (pro-audio vs desktop), and it is not necessarily a bad thing to have separate tools to handle separate needs.

Re:We need to document macOS by ZenoArrow on Monday August 14, 2017 @07:31AM (#15007929)
> "and it is not necessarily a bad thing to have separate tools to handle separate needs."

It's not a bad thing to have different high-level tools for different needs, but in the case of lower level frameworks it's suboptimal unless interoperability is seamless. In the case of PulseAudio and JACK that interoperability is not seamless, and is fraught with problems, so in this regard Linux audio is worse than CoreAudio.

Re:We need to document macOS by CaptSpify on Sunday August 13, 2017 @05:52PM (#15005154)
I'm going to strongly disagree with you. Audio still has a lot of problems experienced by a lot of people. These naive statements are why people get frustrated with Linux. I strongly support FOSS software and use it all day, everyday, but we need to stop saying that our shit doesn't stink.
Re:We need to document macOS by taurath on Sunday August 13, 2017 @07:04AM (#15002431)
I've got Nvidia - probably the core of my problems then.
Re:We need to document macOS by vetinari on Sunday August 13, 2017 @08:25AM (#15002633)
Yes, it is.

For example, there was an article recently, how Nvidia isn't going to support OpenGL acceleration in XWayland.

The keyholder to solve the problems with NV cards in Linux is Nvidia itself. They have all the info, all the sources, and whatever roadmap they planned.

Linux community can solve only Intel and AMD problems, and that's because Intel and AMD are cooperating. Nvidia isn't (Linus' middle finger says hello).

Meanwhile, it is up to you as an consumer, to vote with your wallet and use that to show the vendors your preferences.

Re:We need to document macOS by sd8dgf8ds8g8dsg on Sunday August 13, 2017 @11:34AM (#15003300)
Not sure why NIVIDIA should even invest any time in XWayland. It is just a stepping stone towards Wayland, and the retirement of X11
Re:We need to document macOS by vetinari on Sunday August 13, 2017 @03:59PM (#15004620)
The reason are: games.

All the games (which are of course binary-only, often 32-bit only) released for Linux are linked against SDL 1.2/SDL 2 and X11. It means, that if you are Nvidia owner, you cannot switch to Wayland, unless you are willing to give up gaming (in the current session, at least).

On the other hand, who is buying Nvidia cards? Gamers.

So by not having OpenGL support in XWayland, they have to choose what kind of session they want to run. Many are of course going to choose X11, thus slowing down the adoption of Wayland, delaying the retirement of X11 and of course losing some benefits of Flatpaks (namely isolation at GUI server).

Re:We need to document macOS by josteink on Sunday August 13, 2017 @12:46PM (#15003633)
> For example, there was an article recently, how Nvidia isn't going to support OpenGL acceleration in XWayland

Note: Xwayland, not Wayland itself.

Xwayland is the X11-emulation server running inside Wayland (which itself is HW accelerated).

Not saying anything you claim is wrong, but it's easy to interpret wrong so posting for clarity.

Re:We need to document macOS by sds2 on Sunday August 13, 2017 @08:28AM (#15002639)
> Linux is a great server OS but a really terrible choice on the desktop.

Why?

Re:We need to document macOS by lj3 on Sunday August 13, 2017 @11:53AM (#15003369)
Because I spent 4 hours today trying to figure out how to prevent something from starting on boot (which boot system is Ubuntu using this version? Why do the systemctl and service commands disagree with each other?). I spent two weeks trying to make my ctrl/capslock swap stick and not reset every time the computer slept/resumed. When I plug my headphones into the computer, I have to manually switch the output source every time. If I plug in my external monitor while the monitor is off and then turn it on, linux refuses to recognize it. I have to unplug it, turn the monitor on and plug it back in. Sometimes, when I plug the external monitor in, it won't retain the settings from the last time I used it. It could do the same thing 9 times out of 10, but that 10th time it will decide to mirror the display instead of extend it or something equally silly. Now I have to spend time to fix something that should have just worked.

Is that enough for now? I could go on. I'm using Ubuntu 17.04. Linux on the desktop is still not as easy to use or predictable as Windows or OS X. It's the predictable part that's a deal breaker for me. I want my OS to respond the same way every time I do something, even if that way is wrong or annoying. Every time I sit down to do some work, it's a toss of the dice whether I'll be able to just get into it or if I have to spend some amount of time fixing or resetting or otherwise dealing with nonsense.

Re:We need to document macOS by em3rgent0rdr on Sunday August 13, 2017 @02:42PM (#15004242)
A lot of those issues result with non-uniform hardware. If you want predictability with that then buy from a manufacturer who has designed for and preinstalled Linux, like one of those Dells.
Re:We need to document macOS by lj3 on Sunday August 13, 2017 @03:02PM (#15004348)
It's a Lenovo W530 Thinkpad. It uses standard hardware that Ubuntu officially supports. Been there. Done that. Also keep in mind I've been using Linux off and on since 1999. I'm not a stranger to hardware compatibility issues and none of these problems result from that.
Re:We need to document macOS by sds2 on Sunday August 13, 2017 @05:34PM (#15005089)
You're using linux from 1999 and you've problems like this: "I spent two weeks trying to make my ctrl/capslock swap stick and not reset every time the computer slept/resumed."? It's unbelievable.
Re:We need to document macOS by sds2 on Sunday August 13, 2017 @05:33PM (#15005080)
> Because I spent 4 hours today trying to figure out how to prevent something from starting on boot

Learn systemd then? Or use the "Startup" app?

> I spent two weeks trying to make my ctrl/capslock swap stick and not reset every time the computer slept/resumed.

xmodmap or gnome-tweak-tools?

> When I plug my headphones into the computer, I have to manually switch the output source every time.

I never needed to. See your settings.

> If I plug in my external monitor while the monitor is off and then turn it on, linux refuses to recognize it.

That's your window manager.

> Is that enough for now? I could go on.

Going on with what? With pure laziness from your side to look up tutorials? Or that you use one of the worst window manager/desktop on linux in its almost-beta version and complain about it?

> I'm using Ubuntu 17.04.

That's your problem. 16.04 or switch distros. Don't use unity either. Don't expect things to work when you use (practically) unstable stuff and you don't even know what you're doing.

> Linux on the desktop is still not as easy to use or predictable as Windows or OS X.

None of your claims are true. Just because you misconfigure something somewhere or because you use a crappy window manager it doesn't make the "linux desktop" worse. Windows is not predictable either - I'm forced to use it at work and it's a pretty bad experience overall.

Re:We need to document macOS by S4M on Sunday August 13, 2017 @10:38AM (#15003066)
Sad to see this simple reply downvoted for no reason by a bunch of Apple fanboys.