Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

We need to document macOS

eclecticlight.co

Post reply on HN
Print view View original

171–180 of 266 posts

Re: We need to document macOS

#171

Post by concede_pluto »

comex wrote: post #163
someone7x wrote: post #156

Earlier quoted context omitted.

I'm not GP, but I recently sank time into trying to change Finder searches to default to the current directory instead of my entire machine. It mildly infuriates me that I can't change this; I gave up after I saw com.apple.finder.plist is not plaintext.

Plist files have two standard encodings, an XML-based textual one and a binary one. You can use plutil to convert between the two, e.g. plutil -convert xml1 com.apple.Finder.plist However, for preferences you probably want to use the `defaults` command instead, because IIRC they’re managed by a daemon (cfprefsd) that might not notice if you modify the backing files while it’s running.

When someone decides a config file needs two different serializations and a daemon, I'm reminded of https://www.jwz.org/doc/mailsum.html.

Re: We need to document macOS

#172

Post by em3rgent0rdr »

sooheon wrote: post #167
em3rgent0rdr wrote: post #38

Earlier quoted context omitted.

> "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,…

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.

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

#173

Post by em3rgent0rdr »

jacobolus wrote: post #34
eikenberry wrote: post #16

Earlier quoted context omitted.

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.

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…

Good code can be understood just by reading it. That is practically impossible with binaries.

Re: We need to document macOS

#174

Post by Gracana »

scott_karana wrote: post #161
Gracana wrote: post #154

Does anyone remember "Inside Macintosh," the manuals Apple published back in the classic Mac OS days? I have many of those books, covering everything from how the hardware handles drawing to the screen, up through memory management, files, networking, etc. They're examples of some of the best technical documentation I've ever encountered. It's too bad they don't prioritize that anymore. :(

I remember reading about them in the second paragraph of the article... ;-)

S'not the same to read about it. If you're interested in documentation writing I recommend looking for some of Apple's older stuff on archive.org to see what it's like. I don't see much documentation written in their kind-of extended style these days... A lot of documentation seems to be either terse or tutorial-y, there's not much that tries to focus on the concepts relating to / the purpose of a given feature.

Re: We need to document macOS

#175

Post by valuearb »

mavhc wrote: post #153
ethbro wrote: post #105

Earlier quoted context omitted.

This only follows if Apple indeed wants to kill macOS. If they want users... then you kind of need to have even low level documentation. Because the kind of serious apps and third party feature adds that make an OS bearable to use depend on them.

Of course they want to kill macOS, it's only a small fraction of their profits. They've rewritten all the software they've acquired over the years, Final Cut Pro etc, I'd bet they're internally compatible with whatever their future iOS based desktop OS is.

It's a $25B+ a year business that earns more profits than all the other PC makers in the world combined. I'm pretty sure they don't want to kill macOS.

Re: We need to document macOS

#176

Post by em3rgent0rdr »

throwanem wrote: post #37
eikenberry wrote: post #16

Earlier quoted context omitted.

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.

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

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

#177

Post by throwanem »

em3rgent0rdr wrote: post #176
throwanem wrote: post #37

Earlier quoted context omitted.

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

> "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 afte…

They do, and justifiably so.

Re: We need to document macOS

#178

Post by em3rgent0rdr »

lucaspiller wrote: post #31
eikenberry wrote: post #16

Earlier quoted context omitted.

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.

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.

Well then maybe we all should write enough comments and tests to fully document behavior.

Re: We need to document macOS

#179

Post by spost »

jcelerier wrote: post #155
sd8dgf8ds8g8dsg wrote: post #139

Earlier quoted context omitted.

Please be cautious about recommending KDE's Dolphin. According to Hanno Böck in https://media.ccc.de/v/SHA2017-148-improving_security_with_f... , KDE are refusing to sandbox the thumbnail/preview code, which has proven to be riddled with easy-to-find bugs (using software fuzzing)

how do we know there aren't similar bugs with MS explorer / Finder ?

Well, we don't, but would you rather use software known to have bugs or software not known to have bugs?

Re: We need to document macOS

#180

Post by herbst »

krrrh wrote: post #158
fnord123 wrote: post #129

Earlier quoted context omitted.

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

iirc, they actually contacted Max Howell (creator of homebrew) and got his input on how to make command line tools work better for developers and homebrew specifically.

Assuming this happened and lead to anything it is still far from actually supporting it.
Post reply on HN