We need to document macOS • Hacker News Board

Re: We need to document macOS

#141

Post by digi_owl » Sun, Aug 13, 2017, 3:26 PM UTC

blablabla123 wrote: post #82

SwellJoe wrote: post #58

When I did some work on porting out product to macOS (so developers could run their server environment locally, though a few loons wanted to actually run macOS on servers), I was immediately struck by how awful and incomplete the documentation was. And, I've been working in the Linux world for a couple decades...where docs are copious but wrong about 50% of the time. In particular, the service launcher (launchd, ment…

>And, I've been working in the Linux world for a couple >decades...where docs are copious but wrong about 50% of the >time. Nice summary of the status of Linux documentation. Not sure if it's really 50% wrong, especially the man pages make an impression of over-corrected but the usefulness depends on the tool and is completely random. But yeah, online documentation, classical tutorials are usually useless. When I see…

I wonder how much this has to do with the code, and coder, churns in the Linux ecosystem.

Seems to me that there is a new weekend plumbing project popping up and being replaced almost monthly, if not even more often.

And it if gets an toehold in the ecosystem, the initial developer will quickly move on as he runs out of features to graft on and thus lose interest.

Then whoever takes over invariably decides the codebase in shit, and start over from scratch. And the cycle repeats.

Re: We need to document macOS

#142

Post by BakaRakuda » Sun, Aug 13, 2017, 3:27 PM UTC

stuntkite wrote: post #102

givinguflac wrote: post #97

Earlier quoted context omitted.

I agree. Years ago Finder left much to be desired, but with all the updates of the last few revisions I'm not left wanting for anything. People complaining about searching likely haven't tried smart searches, it's awesome. Can anyone specifically call out what their issues are with Finder besides "it sucks"? I really feel that I'm missing something here.

I have not used smart searches, and now I'm reading about them and it does look pretty cool. But that search bar should give me something sort of close to what I'm looking for in a couple strokes and it really doesn't. I can specifically call out what my issues are with Finder. - Where is my fucking folder tree. There was no reason to take it away other than "thinking different" just like the backspace key. Super spe…

A lot of these just seem like you aren't familiar with the Finder, did you check the menus, preferences, or do a web search for Finder tips?

- No folder tree you are correct. I don't miss it personally. Gotta just deal with this one I think.

- What way specifically does the search not work for you? It's incredibly powerful and you can search by file name, content, file type, creation date, etc.

- It should save the window size you last set it as on a per folder basis when you open a new window from a location. Don't really have any troubles with how it works personally.

- Finder has tabs. Command+T

- Not 100% clear on the problem exactly. If you're going into the wrong folder you don't just have to select a folder by the first character, just keep typing and it will jump to the matching folder name in a list.

- File -> Make Alias

- This one is a bit unclear too. Use spring loaded folders, or a new tab in the location you want to drop to or add the folder to the sidebar that you want to drop files to. Cut and Paste with same named files is a lot better than it used to be and basically works fine now, IMO.

- View -> Show Preview

- Indeed it is designed to keep people away from the system files. 95% of people shouldn't be in there. And of the remaining 1% most of them shouldn't either even if they think otherwise. :P

If you actually need to muck in the system files you can toggle their display in the Finder via a terminal command.

- Command + Up Arrow to go up a directory

- You can open a directory in the terminal easily in a number of ways, including dragging and dropping the folder into the terminal window or icon, using the services menu, etc.

- I don't really find drag and drop copying to be slow in general, are you on a spinning HDD? Anyway with High Sierra the new APFS will make copying files instantaneous.

- There are various services you can use or you can create your own automator services, folder actions etc. to do a multitude of things.

- Finder is decently clutter free IMO, AND it can do a lot of sophisticated things as well.

Re: We need to document macOS

#143

Post by sd8dgf8ds8g8dsg » Sun, Aug 13, 2017, 3:30 PM UTC

yannovitch wrote: post #73

There is a saying in French which says that half of the treatment to get better is to recognize/admit you're sick . There is an other saying which says "Faute avouée est à moitié pardonnée" (If you admit a flaw/mistake, you're already half the way through forgiveness). That to say that maybe there is a lack of documentation because Apple would have to admit to itself (...and to the world) that macOS is not the absolu…

> There is a saying in French which says that half of the treatment to get better is to recognize/admit you're sick

I believe this comes from the 12 step program of the Alcohol Anonymous (religious sect).

1. We admitted we were powerless over our addiction - that our lives had become unmanageable.

Re: We need to document macOS

#144

Post by Drdrdrq » Sun, Aug 13, 2017, 3:30 PM UTC

zoul wrote: post #128

ethbro wrote: post #104

Earlier quoted context omitted.

Not efficiently. And others volunteering their time to reverse engineer documentation on an ever moving target sounds like an exercise in folly. Especially when the first party could hire technical writers for a fraction of the cost of developers and make this problem disappear.

They could solve the problem, but they are not doing it. Trying to force their hand by public shaming may work, but I don’t think it will. Volunteering the effort seems like a pragmatic approach. I would love to have a place where I could send a PR to fix a documentation shortcoming. Adding requests to Radar is futile.

That's not pragmatic, that's just... wrong, on so many levels. Either 1) shame them, 2) move to OSS, or 3) suffer, but please don't donate your precious time to solve the problems of a rich company who doesn't care about its users. Doing so would only diminish the effect of first option (shaming) and is just not fair to anyone.

Or, write a complete reference book and sell it for profit.

Re: We need to document macOS

#145

Post by sd8dgf8ds8g8dsg » Sun, Aug 13, 2017, 3:34 PM UTC

vetinari wrote: post #77

taurath wrote: post #55

Earlier quoted context omitted.

I've got Nvidia - probably the core of my problems then.

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…

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

#146

Post by throwaway413 » Sun, Aug 13, 2017, 3:35 PM UTC

sds2 wrote: post #83

taurath wrote: post #39

Earlier quoted context omitted.

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 do…

> 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 doe…

Seriously - I prefer text-based config via CLI

Re: We need to document macOS

#147

Post by [deleted] » Sun, Aug 13, 2017, 3:39 PM UTC

fnord123 wrote: post #129

notalaser wrote: post #109

Earlier quoted context omitted.

> But, I'm kinda baffled why anyone would volunteer to provide free labor to one of the largest and most profitable companies in the world. YES! MacOS users don't need to document macOS as a volunteer project, they need to demand Apple to give them their money's worth.

And yet Apple does not contribute to homebrew at all. The one project that makes osx usable for developers.

[deleted]

Re: We need to document macOS

#148

Post by zoul » Sun, Aug 13, 2017, 3:45 PM UTC

Drdrdrq wrote: post #144

zoul wrote: post #128

Earlier quoted context omitted.

They could solve the problem, but they are not doing it. Trying to force their hand by public shaming may work, but I don’t think it will. Volunteering the effort seems like a pragmatic approach. I would love to have a place where I could send a PR to fix a documentation shortcoming. Adding requests to Radar is futile.

That's not pragmatic, that's just... wrong, on so many levels. Either 1) shame them, 2) move to OSS, or 3) suffer, but please don't donate your precious time to solve the problems of a rich company who doesn't care about its users. Doing so would only diminish the effect of first option (shaming) and is just not fair to anyone. Or, write a complete reference book and sell it for profit.

You could say the same thing about many free software projects created for the ecosystem. Many of them could have been created by Apple and shipped as a part of the system. I have donated my precious time to solve problems that should have been solved by Apple before. I’m not extatic about it, but my itch got scratched and hopefully I may have helped other people, too, so I consider it a pragmatic improvement. I can see your point, though, so let’s simply disagree, it’s good for the world to have different people try different approaches.

Re: We need to document macOS

#149

Post by pvg » Sun, Aug 13, 2017, 3:48 PM UTC

userbinator wrote: post #127

Apple has always been vague and stingy with the documentation; despite the author mentioning this, In the days of classic Mac OS, when print publishing was growing as a result of Macs, Apple published an exemplary series of books under the banner Inside Macintosh I have read the Inside Macintosh books but they still felt somewhat incomplete and superficial (although they're definitely a little prettier) compared to w…

I have read the Inside Macintosh books but they still felt somewhat incomplete and superficial (although they're definitely a little prettier) compared to what I'd consider close to a "gold standard" for documentation, the IBM PC/AT Technical Reference and the same one for MS/PC-DOS.

One of these is a foot of big books documenting a GUI system and its components, the other is a single volume that tells you handy things like 'The PC/AT has three programmable timers'. I don't think the documentation was ever complete but Apple did produce a lot more of it and had a lot more to document to begin with. The level of documentation is not really directly comparable let alone a symptom of some non-existent 'just works' culture and attitude. If anything, one could make a reasonable argument Apple of the time spent too much effort on beautifully documenting piles of things that were ultimately not useful or successful.

Re: We need to document macOS

#150

Post by lj3 » Sun, Aug 13, 2017, 3:53 PM UTC

sds2 wrote: post #80

LeoPanthera wrote: post #24

Earlier quoted context omitted.

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.

> Linux is a great server OS but a really terrible choice on the desktop. Why?

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.