Why are help docs written for Mac users only?


Several of the help articles assume that the reader is using a Mac. These are core, basic help articles, like Getting Started (https://atom.io/docs/v0.165.0/getting-started) and Customizing Atom.

It’s frustrating. It’s especially bad practice because the docs don’t even say that they’re meant for Mac users. They’re written as though the universe is a place where only Macs are known to exist. At the very least, the start of the article should say “This is written on the assumption you own a Mac.”

If you think all the cool kids use Macs, you might want to talk to people in developing countries.


My understanding is that this is caused in part by Atom not being 1.0 yet. Folks just haven’t had time. I also remember a posting where they said they weren’t sure how to express the system dependent keymaps, for example.


Taking my moderator hat off for a moment:

I find it interesting hearing this kind of complaint about an open source project. If all the “cool kids” are on Windows and there are so many more of them*, then why is this a problem at all? All the bazillions of Windows users should be able to get together and fix up the documentation in no time at all! :stuck_out_tongue_winking_eye:

* Over 91% of the world uses some flavor of Windows according to what I believe are your own numbers. That’s over 10 Windows users for every user of any other OS.

To nudge things back in a constructive direction, what help do Windows users need to contribute more? Windows users’ needs would definitely get addressed sooner, faster and better with more Windows users contributing.

I also wrote a blog post about getting past my own hangups over contributing to open source about a month back:

I really need to make that icon smaller …

Putting moderator hat back on:

Here is the topic that @kgrossjo was talking about:

I understand that it is frustrating. You might want to take a read through this other discussion to see how your approach could be modified to get more people on your side and encourage constructive discussion:


I’m sympathetic to the idea that people sometimes approach open-source projects with a strange sense of entitlement, of give me this and give me that…

I was especially annoyed with the docs because of the lack of even a parenthetical (ctrl/cmd), which is almost idiomatic at this point. As far as contributing to the docs, I’m happy to (I’m also in the process of re-writing Google’s Protocol Buffers intro, on my own, for the benefit of humanity, which I’ll probably trot out as an example of unclear/clear explanation of a new technology.) There might need to be separate forks for Mac, Windows, and Linux instructions. I can imagine three tabs on top where people just click on their OS. Or not – maybe it’s easy to do with sprinkles of clarification and parenthethicals here and there.

Almost all the current docs are aimed at developers who want to write a theme or package. The concept of a user in the normal sense is virtually absent, as is the concept of a Windows user. This might just be what Atom is and what Atom wants to be.

More reflectively, I’m surprised at how pervasive the Mac assumption is in numerous open-source dev tool projects. This must reflect some kind of demographic reality, or skew in who is creating these sorts of projects, who they’re creating them for, etc. From a technical standpoint, I’m bummed at how rare it is to see anyone really take advantage of the Windows platform, to dig into the architecture, libraries, etc. and build high-quality and superfast native apps. The Windows versions of tools like GitHub and Atom seem to be second-class, or after-the-Mac-release situations. Maybe this is Microsoft’s fault. I think they should consider some kind of Reference Apps program to demonstrate what you can do in modern Windows if you really focus and dig in. In Atom’s case, I think it would be interesting to see a typographically aware text editor. The terminal look is standard with text editors and kind of cool, but I wonder what perfectly crisp text in a paper-like environment would feel like – maybe that’s themable, but to really get there in Windows you need to go with DirectWrite, a subset of Direct2D and DirectX. There’s something like this on the Mac. I don’t remember what tools Atom uses, but this might be possible in QT now. A topic for another thread I suppose.

Why is Atom so slow?

I agree about the current state of the docs, but I think this is really because the docs are still alpha in a lot of ways – they wrote what they needed to to get the Atom community going, and now that it’s going, we can help make them better.

Atom was first released only for Macs at first, and the docs haven’t been totally revamped to reflect that Atom isn’t Mac-only anymore. I understand your frustration, but I don’t think there was any malicious intent here, just an oversight that has slipped through the cracks for awhile now. Even though I’m a Mac user myself (spent most of my life on Windows though), I also noticed the Mac assumption in the docs and intended to make some Pull Requests to fix that.


If you look at the first topic I mention in my earlier post, I think it has a great discussion of the different possible approaches for this.


Closing this topic in favor of the original.

closed #8