Coming from Emacs, but playing with Atom on Windows at the moment – why does the documentation say “Cmd” when in means “press the control key”? That had me confused.
Why are help docs written for Mac users only?
Flight manual keybindings on windows
Keybind Documentation is Confusion for Newbies (Like Me)
Flight Manual Keyboard Shortcuts Wrong?
Keyboard mapping for windows
Provide proper multi-OS docs
Non functioning keyboard bindings cited in the Flight Manual
Cannot reproduce "Atom Flight Manual"
Why is the Flight Manual still Mac-only?
Moving in Atom article
Because this whole project and the community is heavily Mac-based still.
I’m sure that will be changed in the docs to accommodate both at some point.
I’ve actually had a offline discussions with community members around how best to document these differences. I’ll probably post something later.
I hate it when docs say something like cmd/ctrl everywhere.
Can I argue that Mac users are smarter when it comes to knowing these things than windows users? In other words just use Ctrl everywhere. Maybe a standard note on every page.
The problem is when the keys don’t map directly or when there are multiple keys even on the same platform. Examples:
- Cmd+Down on OS X
- Ctrl+End on Windows/Linux
- Shift+Ins on Windows
- Ctrl+V on Windows
This isn’t simply an issue with cross-platform support. I would like to find a solution that helps everyone.
Let’s not get into OS superiority complexes over this.
Here’s the (admittedly somewhat small) problem:
Everyone knows what
Ctrl means - because everyone knows Windows. (That is why both Win and Mac users know what to do with that).
Mac commands, on the other hand, are, objectively, still used by a minority and though most Win users can figure this one out as well, some Mac terminology is simply not as well-known.
The fact of the matter is: As long as there are different systems that a program runs on, you have only three choices:
- Ignore all but one frame of reference: That’s a problem, as @leedohm points out, where it can’t be mapped over 1:1, so you need to mention exceptions in your docs in those cases.
- Mention them all across your docs: e.g. Cmd/Ctrl (I don’t see a problem with that unless one is a bit uppity about one’s OS)
- Create your own terminology for everything: Probably the worst option, making it difficult for everyone.
How to improve Atom
I don’t know that @mark_hahn was necessarily being uppity. We all prefer what we prefer. It is in our nature to believe our way is at least better, if not best … otherwise, why the heck is it our way, right?
My ideal solution to this is to have something akin to the Keybinding Resolver behind the documentation so that I could add something like
<span class="keyboard">core:paste</span> to the Markdown and some fancy CoffeeScript would detect the viewer’s OS is Windows and replace it with “Shift+Ins or Ctrl+V” whereas when I went to the same page it would be replaced with “Cmd+V”. It would also read this from the current version of Atom that the documentation was for, so it would automatically update along with Atom.
And then, since I’m really dreaming … we could make it so that it worked for the package listing on https://atom.io/packages. So that when a community member publishes a package and mentions a command with an associated keymap in the README, it would work the same as the main documentation.
Sadly, I don’t have the time to figure this out along with all the other things I want to do for Atom
Useless Documentation due to Keybindings Overwriting (Vanilla Install)
This would by far be the best approach to deal with the problem. In theory, it shouldn’t be that hard to do as long as the packages provide the relevant information.
A related aspect here is that OSX users profit from Emacs-like keybindings, as explained here:
Does anyone know of a solution for this for Windows users? Ctrl+A on Windows means “select all”, in Emacs it means go to beginning of line…
Oh yeah? Well, how do I press this combination mr smart person? -
And there’s plenty of those around the docs.
Sorry, but how great one feels about themselves because of their OS choice is one of the last things I want to hear after dealing with this issue.
Anyways, I am planning to do what was suggested by @jedthehumanoid in a similar topic that I created - fork the docs, add the combinations and submit pull requests. The only thing I would like to know at this point is if they will be willing to accept partial docs, cause I doubt I will be able to do the whole thing in one go.
PS I think it would also be nice if there was an ‘Improve documentation’ link on each docs page that would lead to the corresponding files on github.
PPS @leedohm thanks for closing my topic, but to be honest I think it had a better title then this one, any chance we can update it? (something along the lines of “Provide cross-platform keyboard in the docs”?)
Yes, Pull Requests for partial fixes have been accepted and will continue to be accepted.
Please submit an Issue for this, it is a good idea.
Since mentioning a topic posts a link to it, people will be able to find their way here even if they find your topic first in the search. Also, others may find their way back to this topic by searching for what they remember of its quirky name … I know I do