Live data from Hacker News

We need to document macOS

eclecticlight.co

1–10 of 266 posts

Re: We need to document macOS

#2
> Yet Apple’s documentation for users and those supporting users has all but dried up

You and me we both RTFM, but the population at large? Not so much. When computers were in their early days more of the people that used them were willing and even interested to learn a lot about what was going on. Now the computer is a tool used by most people to do specific tasks. Just like I don't care to learn how to fix my car they don't want to learn how to troubleshoot software nor hardware problems with their computers.

So it might not make economical sense for Apple to spend any significant amount of money on employing technical writers.

Re: We need to document macOS

#4
TFA gives two very disparate examples of documentation failures (basic use of the dock vs service management and the init system). What does the author want to write? A book in the style of the For Dummies series? Something more like the Windows Internals books? Both, everything in between? Some of those surely already exist...

Re: We need to document macOS

#9

I find most answers I need on Stackexchange. However there are books like "Mac OS The Missing Manual", I always wondered if anyone bought them and what they actually contained.

My thoughts exactly. First thought was what problems did this person run into that can't be found in a single google hit today? I was thinking the piece would go into some obscure internals but that doesn't seem to be the case.

MacOS is simple enough to grasp for most people at first use. More advanced usage is documented, not in one location but scattered over the internet. Google made that not matter anymore.

In addition, most documentation you would need today is for the products you install I guess, not macOS. But again, it really doesn't matter much with Google finding anything you search.

My experience with (large) documentation projects. They are outdated almost always. Q&A style works much better nowadays.

Re: We need to document macOS

#10

When it's documented it cannot be changed as easily, so it's often better to not document everything in detail.

Then your users find that their own memory of where to find things and how to perform tasks is unreliable. Has the system changed or they forgotten it? You're effectively "gaslighting" your users if you rely on this.
Post reply on HN