Difference between revisions of "Talk:Beginners' guide"

From ArchWiki
Jump to navigation Jump to search
m (Static IP: rw)
(Wired network configuration: re)
Line 188: Line 188:
  
 
:::Both pose didactic problems in my view. [[netctl#Basic method]] is a wrong start because you have to configure a profile. [[netctl]] works, but we would make BG users wade through a lot of content unrelated to configuring a basic first ethernet link in install chroot. To eliminate the note, we could accept duplicating the "start/enable profile" commands to the end of [[Netctl#Wired]] as an alternative. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 12:06, 29 March 2015 (UTC)
 
:::Both pose didactic problems in my view. [[netctl#Basic method]] is a wrong start because you have to configure a profile. [[netctl]] works, but we would make BG users wade through a lot of content unrelated to configuring a basic first ethernet link in install chroot. To eliminate the note, we could accept duplicating the "start/enable profile" commands to the end of [[Netctl#Wired]] as an alternative. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 12:06, 29 March 2015 (UTC)
 +
 +
::::[https://wiki.archlinux.org/index.php?title=Beginners%27_guide&diff=368240&oldid=367926 This] is my proposal, what do you think? If you agree, please close this item, since I'm happy with the current state of the section (thanks guys for the help). — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:53, 2 April 2015 (UTC)

Revision as of 14:53, 2 April 2015

Unification

A single, unified official install guide

Note: This is based on talk/consensus in #archlinux. The official Installation Guide page is going to be expanded (or this guide could be protected, cleaned up and replace it - either works, that could be decided here).

Previously, there has been talk here about merging with the old official install guide, and just having a single official Installation Guide. However, that didn't happen when the old guide was removed because the Beginners' Guide was (and is) too long, with too much duplication of other pages after the point where it's necessary (getting the initial network access). In order to be an "official" document, it would also have to be protected - edits by regular users would be proposed on the talk page.

The installation process now always requires network access, and the ISO ships with both a browser and an IRC client, so it's not necessary to keep so much information on this page, since we have very good coverage elsewhere that surpasses the duplication here. For example, there's no need for the Beginners' Guide to explain how to do an upgrade as Pacman#Upgrading packages has much better coverage of the gritty details, and the initial install is already fully upgraded.

-- thestinger (talk) 21:52, 28 October 2012 (UTC)

Yes, the ISO comes with a browser (elinks), but it's not very good with formatting. Some people may prefer to actually print the guide (which is a waste of paper, if you ask me, but old timers may feel differently), or save it as a PDF/HTML and read it on whatever device they own (smartphone, tablet, etc).

No need to create a section for this, just reminding that the unification would affect FS#36111. -- Kynikos (talk) 06:57, 18 August 2013 (UTC)

Define scope of the guide

I'd like to define the scope of the guide(s) better and whether it's OK to remove certain things from the wiki instead of marking them as 'the old way' and maybe moving them to a separate article, if needed. Currently the beginners' guide still has info related to initscripts, like setting the timezone, but the article on time has not. -- Karol (talk) 09:56, 30 October 2012 (UTC)

Right now the Beginner's Guide is "A page where user can get their system installed without reading other pages". This is where the duplications come from. Maybe we can redefine it. So we can:
# Improve Help:Reading. Add some guide about Navigation, Searching, Category and Table of Contents. So users can reach the information they want more easily.
# Reduce long duplication texts. The two network configuration part is a candicate. -- Fengchao (talk) 07:46, 31 October 2012 (UTC)
The reason for using the manual way of configuring is actually because timedatectl and friends won't work from inside a chroot. We could avoid that by having users reboot before configuring this stuff (time, hostname, etc. aren't critical at all) but that would require some minor restructuring, so it's something worth discussing. thestinger (talk) 17:28, 3 November 2012 (UTC)
[This comment was pasted here from a different, now deleted discussion]
I think that the goal of the Beginners' Guide is not only to let an Arch novice install the system successfully, but also to introduce him to how an Arch Linux system is structured and the technologies it's based on: we shouldn't think of the Beginners' Guide (or any other article) as a simple howto or step-by-step guide, but as something more formative. -- Kynikos (talk) 15:40, 19 September 2012 (UTC)

Plan

If someone was interested and had the time to lay out here a detailed plan with indications on where to merge every section of the guide and a report of all the problems that could be encountered in the process, it would definitely be the final step before announcing the unification on the forums with full support from the admins, which would mean that at that point only strong and reasonable objections could prevent the unification. -- Kynikos (talk) 06:44, 18 August 2013 (UTC)

Here is a list of sections that should be merged. Feel free to expand, comment in #Comments. -- Lahwaacz (talk) 18:26, 31 August 2013‎ (UTC)

General problems

  • timedatectl, hostnamectl, localectl etc. won't work from inside a chroot, so manual method of configuration is required. This could be avoided by having users reboot before configuring this stuff (time, hostname, etc. aren't critical at all). (mentioned in #Define scope of the guide by User:Thestinger)
You might say these are important enough to have users execute by hand (and thus get a better understanding of, hopefully). But as the underlying processes are explained well enough in their respective articles, I'm fine either way. -- Alad (talk) 06:34, 20 February 2015 (UTC)
  • parted examples mentioning ext3, when partitions are later formatted with ext4, may cause confusion.

Comments

Installation template

Another alternative way to unify the two main guides would be to follow the same philosophy we used to write the scenarios in Dm-crypt_with_LUKS/Encrypting_an_entire_system, originally discussed in Talk:Dm-crypt#New_idea: the new installation guide could be a bare, though complete, list of commands and simple instructions needed to install the system in one example scenario, with links to the various relevant articles for detailed information and adaptations to specific cases. -- Kynikos (talk) 21:18, 27 March 2014 (UTC)

Well, the Beginners' guide suffers from issues related to both content and style, and I really think they need to be addressed at the same time. Every suggestion so far deals only with one problem.
Content: I agree that the purpose of the guide (be it Beginners' or Installation) should be to describe only one scenario and provide links to other articles describing the alternatives. I really like this part of your suggestion, but it solves only half of the problem.
Style: The biggest problem is that Beginners' guide is unique mixture of introduction to reading ArchWiki and introduction to installing and using Arch Linux, which are simply inseparable in the context of BG - you just can't expect newcomers to first read Help:Reading and only then start installing their system. So, there is a little bit of anarchy, as the BG is mostly excused from the style guidelines and there are no guidelines specifically for the BG. Unifying the two guides would necessarily mean a compromise regarding style, which would not be the best for either beginners or gurus.
Also, I think that it is a good thing that BG is readable without reading other pages (as defined in #Define scope of the guide), because it implies that the most important things have been collected and the readers don't have to click-and-search too much. This is really important for the newcomers, because the orientation in the graph of internal links (I wanted to visualize the graph, but it's just too big) is really difficult - they would need to read dozens of pages (with some alien style applied) before they had the basic system running. On the other hand, one of the main points of BG should be to prepare the readers for other ArchWiki articles, but sometimes the readers are too spoiled.
Well, that is my defence of keeping both IG and BG. In my opinion it is enough to just properly define the scope of BG and trim it down to ease the maintenance, addressing the content part. But of course if there is a suggestion on merging the two guides addressing the style issues, let's hear it!
-- Lahwaacz (talk) 11:16, 30 March 2014 (UTC)
About the style issue, I don't think experienced users would be so bothered by some pacman, systemctl or nano examples, and the unified guide should probably explicitly warn users that they won't find similar examples in the other articles, which would be a perfect way to invite them to become familiar with pacman, systemd, Help:Reading... Besides, if the guide will be properly structured, experienced users who don't have their own custom installation notes will be able to just follow the automatic ToC as a memory refresher.
I disagree that the fact that the "BG is readable without reading other pages" is a good thing, as that's exactly the reason that makes it hard to maintain and encourages duplication of information; if users were used to follow links instead, most of the efforts now spent in improving the BG would be instead spent in properly improving the linked articles, which would then become as easy to follow as the BG is now.
Anyway, I've proposed a change in #Comments (under #Plan) that I think should be more likely to reach general consensus, and that would already be a good step forward.
-- Kynikos (talk) 03:35, 31 March 2014 (UTC)
I'm beginning to understand the need for merging. After the BG is slimmed down to cover only one example scenario, the title will be just wrong and the scope will be exactly the same as for IG. It all depends on whether different target audience and related style differences are enough to justify two guides.
I hate being the blocker, so let's slim down BG and when it comes to the point of merging with IG, at least it will not be so shocking. I can't help but to think about it as simple redirecting of BG to IG, which will be (more or less) the eventual outcome, so I will need some time to absorb.
Finally, we should also look at ArchWiki:Requests#Cleanup: installation category, so that Category:Getting and installing Arch is actually useful for providing alternative scenarios, and to ensure there is a place where to move excessive information from the BG.
-- Lahwaacz (talk) 07:35, 7 April 2014 (UTC)
You are not "the blocker", every opinion is as valuable as the others if well argumented, be it for or against the proposal. Especially in this case where we seem to be the only 2 people interested in discussing...
If the unification will eventually be completed, of course the BG will become a redirect to the IG, and the latter will be unprotected (and well watched so it's not turned again into a BG).
Let's go on with the change very gradually, that's definitely the best way to let everyone successfully and happily adapt to the new way of following the document, which, if done properly, will be even easier and clearer (no need to compare two guides anymore, just to mention an advantage).
Of course ArchWiki:Requests#Cleanup: installation category is strictly linked to all this, I'll try to get there too.
-- Kynikos (talk) 05:26, 9 April 2014 (UTC)
I personally would suggest leaving the Installation guide locked after the merger (even if that would lock me out also :). Thing is, if someone went through the effort of researching an addition to the guide, it would be easy for them to bring it up here, in the talk page, and easier for the community to discuss (and implement, if applicable).
Leaving the Installation guide unprotected however would make it open to hasty edits. Even if the IG were well watched as said, a made edit's context may not be sufficiently clear to "judge" it on the spot (confirmed by ArchWiki:Reports). Having contested content remain (however short) on the main, "official" installation reference is less than ideal.
A compromise may be similar to the IRC page, which is not protected in the technical sense, but has a warning urging users not to edit the page without prior consensus. -- Alad (talk) 23:30, 19 February 2015 (UTC)
Once upon a time, I absolutely don't even remember where, we even discussed the option of keeping the guide in a protected page, but do all the modifications in a separate open page (as if they were two "master" and "devel" branches), with the admins periodically approving and merging the unstable page into the official one. Thanks to the recently introduced Special:MergeHistory tool, this job could be easier nowadays. — Kynikos (talk) 14:06, 20 February 2015 (UTC)
That sounds like a good option. Working hypothesis: to make users accustomed to the idea, we could now add a note at the top of the BG, suggesting to first discuss changes on the talk page. After the merger this note would then point to the "development" page. -- Alad (talk) 20:39, 16 March 2015 (UTC)
I think that Special:MergeHistory is too primitive tool for this, AFAIK its only way of operation is "merge all revisions up to specified one", i.e. there is no cherry-picking of feasible revisions. -- Lahwaacz (talk) 20:50, 16 March 2015 (UTC)
@Alad I'm still thinking about it, I'm not sure whether having 2 protected installation guides would be too confusing. The branch method would certainly be well suited if we really ended up merging the guides into one.
@Lahwaacz The way it would work would be (master is protected, contains the whole revisions history and will not receive direct edits by anyone, including admins):
  1. develop is initialized with a simple copy of the latest revision of master
  2. Some users make some edits to develop
  3. The wiki staff amends/undos develop as necessary with additional edits (like it happens now in the only branch)
  4. Once develop is considered in a good state, Special:MergeHistory can be used safely, no need for cherry-picking
  5. Go back to 1 (at this step develop is a redirect to master)
Kynikos (talk) 13:09, 17 March 2015 (UTC)
A simpler alternative with the same effect would be maintaining a link that points to the latest officially approved revision in the history of the article, for example in a Note in the intro. — Kynikos (talk) 13:13, 17 March 2015 (UTC)
Take your time, it will take a lot more work to get the BG anywhere near ready for merging. A link with note sounds viable as well; we could add a table with different options below. -- Alad (talk) 22:08, 17 March 2015 (UTC)

Blacklisting radeon module

Installed Arch on my laptop, during pacstrap the screen went blank, pressing SPACE, CTL+C ... didn't helped only modprobe.blacklist=radeon enabled me to go through the whole installation process. My graphic card is ATI M96 aka Mobility Radeon HD 4650. I believe this info and similar problems should be added to the beginner's guide on a Installation's Issues Troubleshooting section. I believe this is important enough to dual post and separate it from the Removing "Kernel modules" talk. p.s. I may add that this is my first desktop Linux experience--Dhead (talk) 06:20, 4 March 2013 (UTC)

The beginners' guide should not contain hardware-specific info, if the issue is common enough links can be added to Beginners'_guide#Troubleshooting_boot_problems. -- Alad (talk) 14:40, 27 December 2014 (UTC)

Newbie here offering thoughts on what could be changed in guide

General troubleshooting

Apart from that there should be a section at the very beginning explaining how to troubleshoot your own problems. Learning dmesg -HLkd and journalctl -b etc were helpful tools for me. I also appreciated learning lsblk, lsmod, ls etc from the various articles, but a quick over view of these helpful commands on this page would help newbies like myself. Victoroux (talk) 14:01, 7 June 2013 (UTC)

Sorry! Just reading over again, and realizing that I could've saved a tonne of time if I knew the problem of "a bunch of white letters clustered on my screen" was an error I could check. It usually happened when the firmware didn't support something (in my case) but telling the user what he can do when this happens helps ease the wiki hopping. I finally, finally figured out how to debug most of my own problems and I think that is the number one thing this guide should do. No offense, but it would also lessen the load on the "newbie corner" on the forums (not that I know it's loaded or not, but less is better, right?). That way no matter what's written in the guide, if it's incorrect or leads to a bad result, the user can figure out why and what to do.. Victoroux (talk) 14:05, 7 June 2013 (UTC)
Another useful article that could be mentioned (rebooting from black screens, yay!) Victoroux (talk) 00:27, 8 June 2013 (UTC)
Regarding your second point, General troubleshooting is in Related articles - it could be expanded there. --Alad (talk) 14:25, 2 July 2014 (UTC)

Mounting partitions and dual-boot

And lastly, the surprisingly tricky bit about "mounting" partitions that do not belong to you on a dual boot system. Ultimately for me what ended up working was knowing which file systems the others could read (esp in a UEFI system). These things can't just be "linked" to because even the pages linked to don't have the information. I got quite a bit of help from friends and google. Victoroux (talk) 14:01, 7 June 2013 (UTC)

Gummiboot instructions are out of order.

I'm not certain if this is the same issue as the heading "gummiboot instructions are confusing?", but I encountered this using the Beginner's guide. In "2.4 Mount the partitions", it mentions that you should mount the ESP at /boot. But then in "2.8 Chroot and configure the base system", the root is changed to the new system's mountpoint, and /boot no longer refers to the mounted ESP partition (because this was mounted in the live installation CD, in zsh). When in "2.12.2 For UEFI motherboards" I run the gummiboot install command, it errors saying that it is not a fat32 partition. Furthermore, I'm not sure if I need to actually have the initramfs files that were made during pacstrap in the actual ESP since they were installed to /boot. (My thought is they should be, because the assumption was that the ESP has actually been mounted on /boot since before pacstrap was run.)

I'm not certain what to do. (I'm new, this is my first time going through this guide.) Could someone please review this? Or perhaps I made a mistake somewhere...?

Tmarks (talk) 14:23, 11 October 2014 (UTC)

Hmmm... After that there's a command telling about mounting to /mnt/boot, so people must mount it correctly to /mnt/boot. But I think you are right, I's a bit confusing and we should replace preceding /boot with /mnt/boot -- Kycok (talk) 11:00, 15 October 2014 (UTC)
I am not sure I follow this completely; the quoted section numbers anyhow. Beginners' guide#For UEFI motherboards states "It is strongly recommended to have the EFI System Partition mounted at /boot as this is required to automatically update Gummiboot." and then "(replace) $esp with the location of your EFI System Partiton, usually /boot" right before the gummiboot install. Maybe it was updated meanwhile, do we need to adjust something? --Indigo (talk) 20:54, 2 January 2015 (UTC)

Hardware clock section

The Hardware clock section instructs users to set their hardware clock to UTC time:

 # hwclock --systohc --utc

without explaining that this will actually reset the BIOS clock setting. Users are then warned that Using localtime on Arch systems may lead to several known and unfixable bugs.

Question: what might those unfixable bugs be? I've been following these instructions fairly rigorously on every Arch system I've installed, but just got burned by the clock setting, as I think I spaced out and reset the BIOS clock to localtime, so outgoing mail on the system was thrown off by several hours for a couple of days until one of the users alerted me to the problem. Setting the system clock to UTC is kind of confusing, particularly for beginners. What are the unfixable bugs from doing this? If these don't actually exist I would suggest just setting the hardware clock to localtime. This allows you to check the accuracy of the RTC when snooping around in the BIOS.

 # hwclock --systohc --localtime

And if there really are unfixable bugs, users should be told that the hardware clock is going to be set to an unfamiliar value, so they don't freak out when they go in the system setup and find that the clock is off by several hours from the time they thought it should be. -- Pgoetz (talk) 22:33, 5 February 2015 (UTC)

arch-general is a probably a better place to discuss this. -- Alad (talk) 06:47, 6 February 2015 (UTC)
OK, I added a note explaining that this command would reset the RTC clock, which is probably good enough for the Beginner's Guide. -- Pgoetz (talk) 08:44, 6 February 2015 (UTC)
I've just finished expanding that section, I hope it clarifies some of the doubts. Regarding the unspecified "several known and unfixable bugs" I second the suggestion to ask in the mailing list. — Kynikos (talk) 03:22, 7 February 2015 (UTC)
Thanks for making those edits -- it's much clearer now. I also like your simplification of my comment. Based on my own experience, it's important to point this out explicitly (that the BIOS clock setting will look funny) even if it is implicitly obvious, if you think about it. "Don't make me think" is not just a rule that applies to websites. <:) -- Pgoetz (talk) 09:52, 7 February 2015 (UTC)
I think the description is good, but a bit verbose for the BG (particularly as this is about booting multiple operations systems, namely Windows). ut-rc (linked from Time#Time_standard) provides some more background, also on the "unfixable bugs".
I'd suggest to merge the more elaborate description to Time, provide a short paragraph on Windows and localtime (and unexpected BIOS clock), and link to the above website. -- Alad (talk) 20:34, 22 February 2015 (UTC)
If you manage to merge the section into Time I think it's a good thing; I also think the external link can be kept only there: if we want to make the section brief, I'd say that what the readers need to know from the BG is only that they have to make sure the hw clock is set to UTC time and that all the other installed OSs must be set accordingly (Arch will consider the hw clock to be set to UTC by default). Then, if they want to know why, or if they want to use localtime for some reason, they can be sent to read Time to understand all the pros and the cons. — Kynikos (talk) 10:15, 23 February 2015 (UTC)

Static IP

I'd like to discuss whether to keep #Beginners' guide#Static IP or not. dhcpcd#Fallback static profile could easily be expanded to cover this, and most (home) routers provide DHCP by default. Having the information in dhcpcd also benefits Beginners' guide#Wired which directly links to that article. -- Alad (talk) 22:20, 28 March 2015 (UTC)

I assume you'd replace it with a link to dhcpcd#Fallback static profile, +1 from me. — Kynikos (talk) 02:19, 29 March 2015 (UTC)
I'm -1 on this idea. Fallback is useful for headless installs, yes, but that's not a BG topic.? If a user starts configuring Beginners' guide#Static IP, this means default ISO booting DHCP has failed. Making a static connection fallback only delays startup further in this case.. because DHCP will fail again first.
Sidenote: What one might consider, is open a flyspray suggesting the ISO default dhcpcd config could gain a fallback static IP config (with both 192.168.* and 10.10.* IPs/routes it would probably be reachable for the majority of routers). Doing such might be considered network intrusive by some users though. edit: since it would be a passive config, not really intrusive. --Indigo (talk) 09:57, 29 March 2015 (UTC)
Well, the idea is to change/expand the dhcpcd section first to include fallback as a sub-section. The main content would be a regular static profile, with info merged from the BG, and named dhcpcd#Static profile. I like suggesting a default config though. -- Alad (talk) 11:16, 29 March 2015 (UTC)
Please drop a quick note, if you open a bug for it (I do the same). Sub-section or not, this part makes no sense for BG readers of that section imo. Moving the current dhcpcd content of the section, ok - but that's a neat seven lines including code and not really worth it. Moving the whole section comes at the expense of having it verbose incl. interface identification in dhcpcd. I'm neutral on that. --Indigo (talk) 12:45, 29 March 2015 (UTC)
I also doubted if it was worth the effort, hence my asking. Still, I'd like some relation to the chroot section, if only a Tip for users to save/copy their config for later use. -- Alad (talk) 08:21, 1 April 2015 (UTC)

Wired network configuration

I truly appreciate the intent of [1], but beginners haven't been introduced to systemctl and friends there yet, so I would restore very quick examples without descriptions, recommending to follow the links for details. Other ideas? — Kynikos (talk) 02:28, 29 March 2015 (UTC)

I agree it's good to choose a method and provide it with an example. Restored some content with [2]. -- Alad (talk) 02:46, 29 March 2015 (UTC)
I agree as well. It's a bit of a chicken and egg problem where to describe it appropriately for Arch Beginners. For netctl, I tried to cater that with [3]. Having a working network after the first boot is utterly important. Not sure yet what's most KISS to kickstart BGs. --Indigo (talk) 07:58, 29 March 2015 (UTC)
Perhaps we can link directly to netctl or netctl#Basic method (or add these as a second link), instead of adding a note specific to the BG? -- Alad (talk) 11:18, 29 March 2015 (UTC)
Both pose didactic problems in my view. netctl#Basic method is a wrong start because you have to configure a profile. netctl works, but we would make BG users wade through a lot of content unrelated to configuring a basic first ethernet link in install chroot. To eliminate the note, we could accept duplicating the "start/enable profile" commands to the end of Netctl#Wired as an alternative. --Indigo (talk) 12:06, 29 March 2015 (UTC)
This is my proposal, what do you think? If you agree, please close this item, since I'm happy with the current state of the section (thanks guys for the help). — Kynikos (talk) 14:53, 2 April 2015 (UTC)