Difference between revisions of "Talk:Beginners' guide"
(→Plan: remove striked items)
(→General problems: remove striked item)
|Line 35:||Line 35:|
==== General problems ====
==== General problems ====
* Instructions should be clear and concise, taking the [[Installation guide]] as example.
* Instructions should be clear and concise, taking the [[Installation guide]] as example.
Revision as of 16:07, 28 July 2015
- 1 Unification
- 2 Blacklisting radeon module
- 3 Mounting partitions and dual-boot
- 4 Gummiboot instructions are out of order.
Hardware clock section
- 6 Linked to 'parted' Manual doesn't list ext3 or ext4 for fs-type
- 7 Replace parted with cfdisk/cgdisk
A single, unified official install guide
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.
- Yes, the ISO comes with a browser ( ), 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).
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)
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)
- Merge common parts between Beginners' guide#Establish an internet connection and Beginners' guide#Configure_the_network into Network configuration and just link there.
- Beginners' guide#Prepare the storage devices
- Instructions should be clear and concise, taking the Installation guide as example.
- Beginners'_guide#Troubleshooting_boot_problems lacks coherence, and may need expansion. See #Blacklisting radeon module.
- Add short introduction on differences between BG and other wiki pages. See #Installation template.
- There are too many Note/Tip/Warning boxes.
A closer look at Beginners'_guide#Without_wifi-menu indicates that it is a combination of Wireless_network_configuration#Device_driver, Wireless_network_configuration#Getting_some_useful_information, and Wireless_network_configuration#Getting_an_IP_address. The current plan indicates moving all of it into Wireless_network_configuration#Getting_some_useful_information, but that doesn't make much sense. At this point, we could simply link to Wireless_network_configuration, unless someone is opposed. Pid1 (talk) 20:34, 24 July 2015 (UTC)
- First, thank you for looking into this :)
- The current plan indicates "merging", not "moving", Beginners'_guide#Without_wifi-menu into Wireless_network_configuration#Getting_some_useful_information (or I suppose Wireless_network_configuration in general), which does make sense in order to preserve information that might be present only (or better explained) in the Beginners' guide.
- Now, I have only made a quick comparison between the two articles and it also seems to me that everything in Beginners'_guide#Without_wifi-menu is already into Wireless_network_configuration (and I'd be surprised of the opposite), however even if nobody objects here and you decide to replace the whole section with a link, I'd suggest to remove the content part by part indicating with each edit summary where exactly the removed content is duplicated in Wireless_network_configuration.
- Also, maybe the link should be accompanied by an explicit recommendation to follow Wireless_network_configuration#Manual_setup, and ignore Wireless_network_configuration#Automatic_setup, since we're only establishing the connection temporarily in the live system.
- — Kynikos (talk) 15:12, 25 July 2015 (UTC)
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)
- @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):
- develop is initialized with a simple copy of the latest revision of master
- Some users make some edits to develop
- The wiki staff amends/undos develop as necessary with additional edits (like it happens now in the only branch)
- Once develop is considered in a good state, Special:MergeHistory can be used safely, no need for cherry-picking
- Go back to 1 (at this step develop is a redirect to master)
- — Kynikos (talk) 13:09, 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)
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...?
- 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
/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)
- 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)
Linked to 'parted' Manual doesn't list ext3 or ext4 for fs-type
Hi guys. Recent Arch convert here. Loving it. No bloat! Noticed this during Beginners Guid install though:
In the section on using parted ( Beginners'_guide#Partition_schemes ), it links to the Gnu parted manual at http://www.gnu.org/software/parted/manual/parted.html#mkpart for fs-types, but the (rather dated?) manual doesn't list ext3 or ext4. At this point I 'guessed' ext2 was the right choice... Only to find that LATER in the 'Beginners Guide' page it recommended ext4. Damn! Wasn't sure if I had to go back and re-do. Seemed not. But anyway, confusing for 'Beginners'. Anyway, dare not edit the wiki being an Arch noob at this point. Keep up the good work! Cheers. -- Peterg4000 (talk) 00:53, 7 April 2015 (UTC)
- Yes, this is a rather confusing concept: the file system type associated to a partition is a different thing from the file system that you later use to format that partition... It's explained in a bit clearer way in Wikipedia:Disk_partitioning#PC_partition_types, but we should probably explain it better here too.
- In theory, using "ext2", "ext3" or "ext4" when you use
(parted) mkpartshouldn't make any difference at all, as they all set the same partition type code. What does make a difference is the file system you choose when you actually format the partition in Beginners'_guide#Create_filesystems.
- Of course it's wise to make sure the fs-type corresponds to the file system that is going to be used, but even though I've never tested it, I guess you could use e.g. "NTFS" for fs-type and still be able to format the partition with ext4 or whatever file system you want.
- — Kynikos (talk) 13:49, 7 April 2015 (UTC)
- Oh, so for ext3/4 one should just set fs-type to ext2 in parted (etc). Lesson learnt. A one liner would be good saying something like "If you don't know any better, set fs-type to ext2 (Which is the correct option for ext2/3/4), and then format with ext4 below." -- Peterg4000 (talk) 23:32, 7 April 2015 (UTC)
- Actually, parted 3.2 has an explicit label for ext4:
(parted) help mkpart mkpart PART-TYPE [FS-TYPE] START END make a partition ... FS-TYPE is one of: btrfs, nilfs2, ext4, ext3, ext2, fat32, fat16, hfsx, hfs+, hfs, jfs, swsusp, linux-swap(v1), linux-swap(v0), ntfs, reiserfs, hp-ufs, sun-ufs, xfs, apfs2, apfs1, asfs, amufs5, amufs4, amufs3, amufs2, amufs1, amufs0, amufs, affs7, affs6, affs5, affs4, affs3, affs2, affs1, affs0, linux-swap, linux-swap(new), linux-swap(old) ...
- If they are all mapped to the same partition code is another matter, so I'm fine with the current wording. Alternatively we could leave out FS-TYPE completely, after all it is optional (but this is not reflected in the BG).
- -- Lahwaacz (talk) 14:41, 8 April 2015 (UTC)
- Actually, parted 3.2 has an explicit label for ext4:
- Do we want to reopen and investigate this further? Thanks for reminding of the help command, however I can find many sources that seem to confirm that many Linux native file systems (but not all of the above!) map to 0x83:     . Unfortunately, as Wikipedia:Partition_type#Overview says, these codes are not standardized, so we won't be able to find an official reference. Last thing, quoting the manual, " fs-type is required for data partitions (i.e., non-extended partitions)", so I wouldn't leave it out as optional. — Kynikos (talk) 09:46, 9 April 2015 (UTC)
Replace parted with cfdisk/cgdisk
So, just wanna throw this out there for discussion. I've always found cfdisk/cgdisk to be much more beginner-friendly and intuitive than parted. Since this is the "Beginner's Guide" wouldn't it make sense to recommend using these tools? At the very least, it might be good to mention that they are visual partitioning tools when they are listed in the "partitioning tools" section. Thoughts? -- A Future Pilot (talk) 14:21, 13 July 2015 (UTC)
- Related: 
- I personally wouldn't mind revisiting the topic on fdisk vs. parted (unsure on the benefits of cfdisk or cgdisk - they're not "visual" besides a more-or-less clunky table format, and fdisk has a print switch). This however implies merging Parted content to parted as mentioned in #Plan. -- Alad (talk) 14:53, 13 July 2015 (UTC)
- I personally also favor (c)fdisk. I think it both are very clear for beginners, and they can handle both MBR and GPT (no need for (c)gdisk).
- In any case, I think we should choose a tool which can handle both GPT and MBR partitioning schemes, because otherwise things will get messy again. This is one of the reasons why we changed to parted: it supports both (and back then, there was some question about the stability of fdisk's GPT support, but I'm sure it is fine now; I've personally never has issues). Lonaowna (talk) 17:14, 13 July 2015 (UTC)
- This is obviously too subjective from those being used to one specific tool. I personally find parted to be easier to understand because you write the whole commands instead of just a couple of meaningless letters. Granted, all tools have a help page built in, provide a detailed man page and there is a bunch of "tutorials" for every possible scenario. So, is it even possible to select the "most beginner-friendly" tool or should we decide based on different factor? In any case, there should be only one tool described in detail in the BG and alternatives should be linked to. -- Lahwaacz (talk) 17:23, 13 July 2015 (UTC)
- I agree with your last point, that there should only be one tool described in the BG.
- But I cannot see how we can choose one on other criteria than "beginner-friendly", as all candidates should be able to provide the same functionality. What other factors are there to decide on?
- The only I can think of is that fdisk ( ) is in [core] and , and is not. But both are on the installation ISO, so I'm not sure if that matters at all.
- I am afraid that there is no real criterion to decide by, except for "beginner/user-friendliness", which is indeed subjective. Lonaowna (talk) 21:22, 13 July 2015 (UTC)
- As said, the BG switched from fdisk to parted only a few months ago (which in wiki terms means "yesterday"), so we can't keep going back and forth like in a loop. At this point, I support Alad's proposal above to move the examples to the specialized articles, which also goes in the #Unification direction (and this discussion itself is yet another argument in support of that plan). — Kynikos (talk) 11:49, 15 July 2015 (UTC)