The creation of an Atom Wiki


#1

Hi,

I’d like to suggest that we create a Wiki for this grand text editor. So that the community can contribute tips about what worked and what didn’t work for them as far as installing Atom on the different platforms, installing packages and themes and also to guide new comers in an easy-to-use format of a Wiki. Now I know we have the Atom documentation (like the flight manual), but that is written by Atom developers if I am correct and the community in general cannot edit it. The documentation is also incomplete as far as the information in it (which is not a criticism I am making about its writers, if it were complete it would be impossibly long), hence why I think a Wiki would serve to supplement its content with tips from the community.

As far as venues go, like where such a Wiki could and should be set up, well I don’t see any better place than GitHub itself, as we could have a Wiki that is similar to the Nodejs Wiki. Although if for whatever reason this is unsuitable Wikia and Orain Wiki are plausible and free MediaWiki-based alternatives.

Thanks for your time,
Brenton


#2

Although I’m not opposed to such a Wiki, I wonder how much demand for it is there. What’s the kind of thing you feel is missing from the existing documentation, that isn’t served by this forum?


#3

This isn’t entirely true. While it is true that only members of the Atom organization can edit it directly, anyone (with a GitHub account) can submit a pull request … and even the Atom folks submit pull requests and get them reviewed by other members rather than simply checking it in.

I’m not against there being a wiki too. I just wanted to clear up the misconception.


#4

How to install Atom on Linux distributions. I know there’s documentation in Linux.md but the fact I keep finding it simply doesn’t work on 32 bit versions of Debian, Fedora, OpenSUSE and Ubuntu surely says something about it being out of date or even untested. I’m sure other issues I may or may not find a solution to, to write on such a Wiki, will popup as I use Atom more and more.


#5

I didn’t know it doesn’t work on 32bit Linux distros. Has that been replicated and confirmed?

I think some special cases of restrictions or unsupported systems like this should simply be added to the Flight Manual (i.e. feel free to open a PR to update the page, as @leedohm mentions).


#6

Thanks for the info, I suspected that if I/someone else asked the developers, somehow (you gave me the answer of how) we would be able to get the documentation edited, but still it would probably take at least a couple of days, while editing a Wiki would be more immediate.


#7

I don’t know, generally speaking when I create an issue @ GitHub I get at most one or two people replying to it so it’s hard to know if anyone has reproduced it. If you look at the Atom GitHub repo you will find some of these issues of mine if you look for the Linux tag and my username fusion809. I also posted a question on ask.fedoraproject.org.


#8

@batjko Shall do. At the moment I’m just developing some solutions for him and other developers to add to the flight manual. Although I suspect a lot of pruning will be required because the flight manual is very brief on installation details as far as I can tell and I’m wondering if that’s deliberate or just because Atom developers simply didn’t have all that much to add to the installation part of the flight manual.

As far as my desire to create a Wiki I’m wondering how I should get this idea off the ground, should I start it myself on Wikia or Orain or wait for more people to come to this topic and more developers to develop an interest in creating one @ Atom’s GitHub repo?


#9

How do I do this for the flight manual? Whenever I try to make a pull request for the Atom repo on GitHub I am asked which repo I am to compare, but I have none. I have a markdown file I’d like ya to use to update the flight manual with, in accordance to what batjko has suggested.


#10

This is the flight manual’s repo:


I’m guessing this is the page you’re looking for?

You can either fork it first and then submit a PR for your changes, or if you edit a page directly on that repo, Github will automatically fork it for you and raise a PR for the change, as far as I remember…


#11

The files here aren’t in MD format, so I’m getting kind of fed up… Here’s the Atom installation guide for Linux distros I’ve prepared, the developers can read it and make changes based on it, I ain’t going to spend hours doing this when all I’m trying to do is help others install Atom. This is why a Wiki would be more helpful, making it more simple than contributing to the Atom repo is.


#12

Well look… Your enthusiasm to help is of course much appreciated, but contributing will imply contributing in the technology that is already in use by the core team. So unfortunately, .md is not available any more (used to be), but .asc files aren’t more difficult to edit either.

Having said that, if you would like to start and maintain a Wiki on your own accord, no one would tell you that you can’t.

It might be worthwhile getting someone from the core team to comment here, as to the chances of such an undertaking to get support from the core team in some way.


#13

All that @batjko has stated is correct. It sounds like you figured out the process, even if it is more complicated than you would prefer. If not, more information can be found here:

https://help.github.com/articles/fork-a-repo/

A wiki makes things easier to edit, yes. But it also makes correcting mistakes or inaccuracies much more of a maintenance burden. If you’re not willing to spend hours learning to submit some changes to the official repositories, are you going to be willing to spend hours maintaining a useful wiki? Writing understandable, useful, well-organized documentation is a lot of work, no matter how you slice it. And a bit of an under-appreciated art, if you ask me.


#14

I’ve been trying to understand Git, I read your linked article and it was of no help. I went to here, started a pull request with this https://github.com/fusion809/atom/. I went to https://help.github.com/articles/syncing-a-fork/ and ran git fetch upstream from ~/atom to receive error: cannot open .git/FETCH_HEAD: Permission denied I understand MediaWiki at least and I don’t get any errors out of it any more but git is a pain in the backside.


#15

Git does have a steep learning curve and I have plenty of issues with its user interface (don’t get me started :wink:).

If your upstream remote starts with ssh, then it will try to authenticate you for push access, which you don’t have. But if you switch to HTTPS here:

you’ll get a URL that you can use for your remote that you should be able to use without an issue. You can use the command git remote set-url upstream https://github.com/atom/atom.git to set this. (The URLs are the same for everyone, so that command will just work for you. I just wanted to show you where you could find the information.)


#16

If I was meant to retry this after running this, I’m afraid this isn’t making any difference. Running git fetch upstream still gives: error: cannot open .git/FETCH_HEAD: Permission denied


#17

So it looks like the learning curve for git and Github in particular is the main barrier for you to contribute to the existing docs.

In terms of editing the .asc files, have a look at the actual raw file, it’s very easy to edit, not much different to MarkDown. I’m sure once you got the workflow down, you’ll have no problem adding your PRs.

Like I said, you can actually edit the file right on the repo itself on Github, and Github takes care of the forking and Pull Request raising for you!


#18

OK. How do I sync a fork on GitHub and please don’t send me to a manual as they are useless and irritating to me.


#19

Look, my friend. You don’t like complying to the technology stack that is in use, you don’t like reading instruction manuals, instead you want people to hand you everything on a silver platter in the exact way that you personally prefer it.

With all due respect, at some point you’ll have to try and be part of the community if you’re interested in it, instead of getting upset about that community not wanting to shape itself after your personal proclivities.

I am going to send you to a very good instruction page in fact, which is very well written and should give you everything you need to sync your fork:
https://help.github.com/articles/syncing-a-fork/

But remember, Github forking and contributing is probably not the best place to start learning about git in general. I’d suggest getting familiar with git basics first, e.g. clones, pulling and pushing, what a remote is, the difference between origin and upstream etc…
Once you know that stuff, working with Github is going to be a lot easier.


#20

I have been trying to all you’ve seen is a small fraction of what I’ve attempted to do with Git over the past couple of years. I have read your instruction manual, the syncing a fork article, I wanted you to send me something other than it because your message gave me the impression that there’s a way of syncing it via the user interface of GitHub without using the directory on my machine. I have tried the syncing a fork article but it wasn’t helpful as I mentioned in previous comments with leedohm. If I wasn’t willing to read them I wouldn’t have gotten this far in this discussion, as every article you’s have sent me I have attempt to read and follow but every time I encounter an error with it.

What am I supposed to do to convince you that I’m not sitting on my backside thinking you’re all my slaves?