Installation Guide after "big merge" is too unfriendly to new users?

Jiaan · 2016-08-30 17:27:40

I understand the purpose of "big merge" is to tidy up duplicate and/or obsolete wiki entries. Merging the original "Beginner's Guide" with "Installation Guide" is one of the most outstanding changes. The change is however too radical for me (and probably for some new/potential users).

In the good old days, there was the simple-minded "Beginer's Guide" where you can literally copy&paste the commands, read the explainations and happily end up with a fully fuctional base system! In fact, this is how I did my arch installation when I was basically illiterate to command line. Now all that is left is the installation guide, which was intended for people with some knowlege a priori. A new user may feel frustrated while reading the wiki article that skimps on examples and requires further delving into many other wiki pages. Such practise definetely imposes a much higher barrier to new comers.

For example, suppose I wish to set up arch wirelessly. In the "connect to internet" session of the installation guide, I need to look at the following wiki pages: network configuration, systemd-networkd, netctl, WPA_Supplicant and probably digging into some obsecure man pages and website, then trying to write a systemd configuration file because the wiki suggest to use systemd-networkd. While in the beginner's guide, they just told you to use wifi-menu. In fact that's all you need, simple and stupid, as indicated by the arch philosophy. Even though this approach is not "generic", "orthogonal", and "systemd" enough, it simply works and less scary.

Arch wiki is the very best linux wiki on the web, it serves pedagogical purpose in addition to just a politically correct reference with generic conceptions. IMHO, it would make life easier if we provide more concrete examples on the installation guide. I dare not edit the installation page, so I just make a complain here. Hopefully it will not enrage anyone.

Edition
Thanks for all of your kind reply. You have made some effective points which in fact I would personally agree with. But keep in mind that I am writing this suggestion on behalf of new comers, and fear that my favorite distro will appear too hostile in their eyes. I had this particular feeling when I read the network configuration part of IG. I also wish to emphasis and clarify the followings:

Copy and paste doesn't mean you don't understand what you are doing. In fact there were detailed explainations for what a particular command does in the original beginner's guide. Nor did detailed explainations or examples harm your ability to customize by yourself.
Learining is a process. Maybe it is better to make some demonstration first.
If the installation page engenders confusion and you need to seek for extra help, it is not well written.

And my suggestion is to provide more examples as well as corresponding explainations, which is not harmful at all. Didn't mean to distroy the simplicity of arch, I just wish it better.

Last edited by Jiaan (2016-08-31 05:37:54)

jasonwryan · 2016-08-30 18:15:49

Replacing a copy/paste guide with one where people are expected to understand what they are doing is an enhancement, not a regression.

drcouzelis · 2016-08-30 18:51:59

I just looked at the new Installation Guide for the first time. I used your "wifi-menu" example as a test to see what I would need to learn and do (it also helps that I have NO IDEA how to configure a wireless network connection in Arch Linux...).

It looks to me like the Installation Guide is now:

Much cleaner.
Has less duplicated information.
Easier to read through for knowledgable Linux users.
Provides more opportunites for educating the user.
Provides fewer "copy and paste into the terminal" commands. (Depending on who you are.)

I don't know what the long term effect will be, but it certainly is a different approach compared to what was there before.

...Maybe this is an opportinity for "How to install Arch Linux" blog posts and YouTube videos to flourish? I already jumped on board with the book I was a technical reviewer for!

TheChickenMan · 2016-08-30 19:53:40

drcouzelis wrote:

...Maybe this is an opportinity for "How to install Arch Linux" blog posts and YouTube videos to flourish?

Unfortunate for them that installations using instructions from outside sources won't be supported.

I think the old guide was really unwieldy in some places, especially the old section on networking. It was like half the guide. So much emphasis on networking (especially wireless) was really not needed. Plugging in a wire and configuring dhcpcd or something similar is really all that needed to be said for initial installation. On the other hand I still think the old guide was better to reference when looking at it from a more limited device. It was a lot easier to pull up the "one guide" on a phone or in a terminal browser during install and scroll through than to need to look at various pages. I don't know. Maybe there's a few more things that should be added to the new guide to make it more complete while still keeping relatively streamlined?

Head_on_a_Stick · 2016-08-30 19:54:41

I really like the new guide.

Replacing the copypasta code blocks with man page links is genius, IMO.

eschwartz · 2016-08-30 23:06:56

TheChickenMan wrote:

On the other hand I still think the old guide was better to reference when looking at it from a more limited device. It was a lot easier to pull up the "one guide" on a phone or in a terminal browser during install and scroll through than to need to look at various pages. I don't know. Maybe there's a few more things that should be added to the new guide to make it more complete while still keeping relatively streamlined?

This is the only really good argument against the merge IMHO.

Perhaps something could be done with transclusion?

Trilby · 2016-08-30 23:15:57

Jiaan wrote:

The change is however too radical for me (and probably for some new/potential users).

You certainly aren't alone. I don't personally share the view, but I've seen several much less well expressed displeasure with the change. It is hard to tell what concerns are objectively founded and which ones are just pouting about any change to the familiar. But in either case, thank you for starting the thread here on this in a constructive manner. Though while the approach is constructive, I'm not sure how *productive* it will be. It seems to me the best place for productive discussion of this would be on the talk page of the wiki. But certainly some ideas can be hashed out here first.

TheChickenMan wrote:

Maybe there's a few more things that should be added to the new guide to make it more complete while still keeping relatively streamlined?

Maybe. But what are they. Specifics can be addressed. Generalities can only be speculated about.

Steef435 · 2016-08-31 01:06:50

To be honest my reaction was a bit like Jiaan's the first time I came across the merge. I'm not sure if I would've been able to install Arch a few years ago using this guide. I can imagine opinions vary wildly on whether that's good or bad.

If the guide were to be expanded, I think the "scary" areas should be expanded. If I'm installing a new distro, two things are mainly scary to me:
- Partitioning (please don't kill the other OS on my disk etc.)
- Internet access (especially if you only have one system available, getting stuck without a connection can be horrible because you can't do any online research or ask for help)

Right now, partitioning info is pretty meager in my opinion, I think it would be nice to have a simple, small yet functioning example of a partition layout to get started. Maybe even some instructions on how to get it done using a specific tool, but I'm not sure whether that's necessary, we have man pages for that.

Internet access is absolutely perfect for wired connections, because it simply works out of the box most of the time and if not, you should probably get some drivers. I think this should be logical to anyone, and if not, the wiki pages talk about drivers in detail.

I do agree that wireless connections aren't really touched directly in the installation guide right now, on the other hand. On top of that, wifi-menu - which is practically the wireless equivalent of the automatic wired connection - is hardly mentioned in the wireless configuration page, neither does it show up in the netctl man page. Only on the netctl wiki page it is mentioned a few times. Therefore I would suggest adding a sentence to the installation guide like "For quickly setting up a wireless connection, netctl's wifi-menu can be used."

It seems only fair to me that, if wired users don't have to understand network configuration to get an internet connection, wireless users should be able to get off with minimal understanding as well. That, or both should have to read and understand the network configuration wiki page.

Apart from those two points, I think the new guide is brilliant. I think that newcomers will actually understand what is going on way more than with the beginner's guide. The guide is a lot less complex and that makes it easier to follow. As a side note, I do believe that it's a whole lot of copy paste work, maybe even more so than with the beginner's guide.

One final nitpick with the current guide is that it assumes that the reader can actually edit files (knows a CLI editor). A quick reference to the list of CLI editors would be nice I think. I've made a suggestion in the discussion page.

jasonwryan · 2016-08-31 01:20:28

Steef435 wrote:

One final nitpick with the current guide is that it assumes that the reader can actually edit files (knows a CLI editor).

I think this is a totally legitimate assumption to make when installing Arch.

Arch Linux wrote:

The distribution is intended to fill the needs of those contributing to it, rather than trying to appeal to as many users as possible. It is targeted at the proficient GNU/Linux user, or anyone with a do-it-yourself attitude who is willing to read the documentation, and solve their own problems.

fsckd · 2016-08-31 03:50:35

Jiaan wrote:

In the good old days, there was the simple-minded "Beginer's Guide" where you can literally copy&paste the commands, read the explainations and happily ends up with a fully fuctional base system! In fact this is how I did my arch installation when I was basically illiterate to command line. Now all that left is the installation guide, which was intended for more people with some knowlege a priori. A new user with now may feel frustrated while reading the wiki article that skimps on examples and requires further studying many other wiki pages. Such practise definetely imposes a much higher barrier to new comers.

The goal should not be to get an Arch system. The goal should be to understand your system. Copy and pasting is not conducive to that. If you have trouble understanding something, you should ask. If something isn't clear, ask for an explanation. Asking is very important. That is what the forums are for. That is what the IRC channels are for.

If you want your system to be handed to you on a silver platter, made behind closed doors, Arch isn't for you. If you want to see what is happening, in a way that broadens your knowledge and expands your skills, the wiki is targeting you as a user. You are not going to understand anything if you don't read the man pages or upstream docs. You are not going to understand anything if you blindly follow commands. Arch is for tinkerers and hackers, for people who want to delve deep and greedily. People who do not fear the Balrog.

This does not mean Arch isn't for people who are new to GNU/Linux, people who have never touched the commandline before. If one has patience, is willing to persevere, and is willing to read and ask for help, then they will have no problem with Arch. I have seen many people over the years do just that. They read, they did their homework, they asked when they got stuck. They skipped the kiddie pool and went straight to the deep end. The end result? They have a system they understand. If someone else gets stuck on the same things they were stuck on, they can help. Because they understand their system. If they merely copy and pasted they would not be able to do that.

Teach one to fish. That is the pedagogy aimed for.

Jiaan · 2016-08-31 05:41:26

fsckd wrote:

Jiaan wrote:
In the good old days, there was the simple-minded "Beginer's Guide" where you can literally copy&paste the commands, read the explainations and happily ends up with a fully fuctional base system! In fact this is how I did my arch installation when I was basically illiterate to command line. Now all that left is the installation guide, which was intended for more people with some knowlege a priori. A new user with now may feel frustrated while reading the wiki article that skimps on examples and requires further studying many other wiki pages. Such practise definetely imposes a much higher barrier to new comers.
The goal should not be to get an Arch system. The goal should be to understand your system. Copy and pasting is not conducive to that. If you have trouble understanding something, you should ask. If something isn't clear, ask for an explanation. Asking is very important. That is what the forums are for. That is what the IRC channels are for.
If you want your system to be handed to you on a silver platter, made behind closed doors, Arch isn't for you. If you want to see what is happening, in a way that broadens your knowledge and expands your skills, the wiki is targeting you as a user. You are not going to understand anything if you don't read the man pages or upstream docs. You are not going to understand anything if you blindly follow commands. Arch is for tinkerers and hackers, for people who want to delve deep and greedily. People who do not fear the Balrog.
This does not mean Arch isn't for people who are new to GNU/Linux, people who have never touched the commandline before. If one has patience, is willing to persevere, and is willing to read and ask for help, then they will have no problem with Arch. I have seen many people over the years do just that. They read, they did their homework, they asked when they got stuck. They skipped the kiddie pool and went straight to the deep end. The end result? They have a system they understand. If someone else gets stuck on the same things they were stuck on, they can help. Because they understand their system. If they merely copy and pasted they would not be able to do that.
Teach one to fish. That is the pedagogy aimed for.

Thanks for replying, plz view my edition of original post.

jasonwryan · 2016-08-31 05:57:00

Jiaan wrote:

But keep in mind that I am writing this suggestion on behalf of new comers, and fear that my favorite distro will appear too hostile in their eyes.

I really take exception to this suggestion that Arch is too hostile, or too elitist, or too $insert_your_pejorative_adjective_here

Arch is, and always has been, a distro for competent users. Whether that is competent at the command line, competent at reading documentation, or just competent at thinking for themselves. The goal has not, and has never been, to be all things to all comers. To be popular. To be cool. To be whatever.

If you, or you peers, or random people on the Internet, think that Arch is hostile because the community provided documentation assumes that you will read a man page before installing Arch, that is your/their problem, not ours.

You want something that is auto-installed? Go somewhere else. You want your hand held? There are plenty of distros, just as good as Arch, that do that. What makes Arch interesting to its developers and contributors is the fact that it is user-centric, not user-friendly:

Whereas many GNU/Linux distributions attempt to be more user-friendly, Arch Linux has always been, and shall always remain user-centric. The distribution is intended to fill the needs of those contributing to it, rather than trying to appeal to as many users as possible. It is targeted at the proficient GNU/Linux user, or anyone with a do-it-yourself attitude who is willing to read the documentation, and solve their own problems.

If you have a problem with that, it is your problem, not Arch's. No-one is forcing you, or anyone else, to use Arch. It's just a distro, there are literally hundreds to choose from. Pick one that does tick your boxes.

diskualified · 2016-10-31 04:31:47

fsckd wrote:

The goal should not be to get an Arch system. The goal should be to understand your system. Copy and pasting is not conducive to that. If you have trouble understanding something, you should ask. If something isn't clear, ask for an explanation. Asking is very important. That is what the forums are for. That is what the IRC channels are for.
If you want your system to be handed to you on a silver platter, made behind closed doors, Arch isn't for you. If you want to see what is happening, in a way that broadens your knowledge and expands your skills, the wiki is targeting you as a user. You are not going to understand anything if you don't read the man pages or upstream docs. You are not going to understand anything if you blindly follow commands. Arch is for tinkerers and hackers, for people who want to delve deep and greedily. People who do not fear the Balrog.
This does not mean Arch isn't for people who are new to GNU/Linux, people who have never touched the commandline before. If one has patience, is willing to persevere, and is willing to read and ask for help, then they will have no problem with Arch. I have seen many people over the years do just that. They read, they did their homework, they asked when they got stuck. They skipped the kiddie pool and went straight to the deep end. The end result? They have a system they understand. If someone else gets stuck on the same things they were stuck on, they can help. Because they understand their system. If they merely copy and pasted they would not be able to do that.
Teach one to fish. That is the pedagogy aimed for.

I like that Arch is about learning; that's why I came to it. But I don't think it's possible to learn without at least *some* copy-pasting. You can read the man pages and the docs/wikis all you want, but in the end, you're going to have to type something into the command line, and something is going to happen. The "copy-paste" code and many examples were nice because they at least gave a baseline: this is an example of a well-formed command, and this is what you should expect from it. Without examples, even the more adventurous one would quickly become discouraged by the prospect of stumbling around the dark for *that* long.

The trouble is to determine just how much experience the documentation expects from the users. I know for sure that if I had to install Arch for the first time with the current documentation, I'd either be more clueless than I am now, or I would have quit. I enjoyed the past "Beginners Guide" because it was a good introduction to the sorts of things you should know to learn about and the level of interactivity expected from the Arch user. It holds your hand, just this once, to get you started. That's not so with the merged page. In short, it was a good guide to transition less experienced users.

About asking questions: yes, that's generally a good thing, but how many questions do you want people to have to ask? Speaking personally, I dislike having to post a lot of forums because the answers weren't in the docs. It's way, way messier to consult forums than it is to consult a good, centralized doc. It feels fragmented.

If the goal is to provide solely for those seasoned users who weren't already using Arch, then the installation guide is spot-on. Otherwise, it significantly increases the barriers to entry for less experienced users; the barrier always existed, but it's worth considering its height. My concern is that the barrier is inappropriately high because of the change.

Scimmia · 2016-10-31 04:37:41

diskualified wrote:

In short, it was a good guide to transition less experienced users.

You hit the nail on the head. Arch very specifically and explicitly targets proficient users, not "less experienced" users. See https://wiki.archlinux.org/index.php/Ar … centrality

Last edited by Scimmia (2016-10-31 04:38:00)

jasonwryan · 2016-10-31 04:55:42

And we are done here...

Closing

Arch Linux

#1 2016-08-30 17:27:40

Installation Guide after "big merge" is too unfriendly to new users?

#2 2016-08-30 18:15:49

Re: Installation Guide after "big merge" is too unfriendly to new users?

#3 2016-08-30 18:51:59

Re: Installation Guide after "big merge" is too unfriendly to new users?

#4 2016-08-30 19:53:40

Re: Installation Guide after "big merge" is too unfriendly to new users?

#5 2016-08-30 19:54:41

Re: Installation Guide after "big merge" is too unfriendly to new users?

#6 2016-08-30 23:06:56

Re: Installation Guide after "big merge" is too unfriendly to new users?

#7 2016-08-30 23:15:57

Re: Installation Guide after "big merge" is too unfriendly to new users?

#8 2016-08-31 01:06:50

Re: Installation Guide after "big merge" is too unfriendly to new users?

#9 2016-08-31 01:20:28

Re: Installation Guide after "big merge" is too unfriendly to new users?

#10 2016-08-31 03:50:35

Re: Installation Guide after "big merge" is too unfriendly to new users?

#11 2016-08-31 05:41:26

Re: Installation Guide after "big merge" is too unfriendly to new users?

#12 2016-08-31 05:57:00

Re: Installation Guide after "big merge" is too unfriendly to new users?

#13 2016-10-31 04:31:47

Re: Installation Guide after "big merge" is too unfriendly to new users?

#14 2016-10-31 04:37:41

Re: Installation Guide after "big merge" is too unfriendly to new users?

#15 2016-10-31 04:55:42

Re: Installation Guide after "big merge" is too unfriendly to new users?

Board footer