FS#13140 - Official Installation documentation

Attached to Project: Release Engineering
Opened by Aaron Griffin (phrakture) - Friday, 06 February 2009, 17:54 GMT
Last edited by Dieter Plaetinck (Dieter_be) - Friday, 05 March 2010, 18:56 GMT
Task Type Feature Request
Category archlinux-installer (deprecate
Status Closed
Assigned To No-one
Architecture All
Severity Medium
Priority High
Reported Version 2009.01-beta
Due in Version Undecided
Due Date Undecided
Percent Complete 100%
Votes 0
Private No

Details

This bug is intended to collect a set of complaints for the installation documentation.

I will summarize here:
* The Official install guide in the wiki and the installer is outdated
* The Official install guide should be in the Developer wiki, not publicly writable
* dolby has updated install guide:
http://github.com/grbzks/installer/blob/34083245bce4a35cb96469530aeab0514319f958/arch-install-guide.txt
* The beginners guide should be either removed (as it's post-installation) or renamed to seem less official

Does that cover everything?
Closed by  Dieter Plaetinck (Dieter_be)
Friday, 05 March 2010, 18:56 GMT
Reason for closing:  Fixed
Comment by Greg (dolby) - Friday, 06 February 2009, 18:06 GMT
My modified version of the guide at this point changes mostly:
Removed man pages all the way paragraph. Arch includes documentation now.
Remove seperate kernel installation step as its now part of the packages installation process.
Fixes FS$13046
Removed ext3 support in favour of ext4. All references to ext3 have been converted to ext4.
I am now in the process of writing the Set Clock step but i am a bit stuck.
Some capitalisation think like RAID, LVM.

I am considering removing all lilo references.
I have asked Misfit138, the author of the Beginners Guide to help. He is interested in documentation in general, & a native speaker AFAIK.
All sugestions and of course help welcome.
Comment by Dieter Plaetinck (Dieter_be) - Friday, 06 February 2009, 18:10 GMT
The outdated-ness of the install guide is the only thing arch-releng related.
Most of the problems to documentation apply to *all* documentation about Arch.
I'm thinking of:
* access control
* keeping the documentation official ("hey, who the hell put yaourt stuff in here") <-> allowing community input. community input can be good because they help us, but some of the changes might not be what we want.
* generating packaged documentation

Maybe we should come up with some sort of policy/workflow about all our documents that takes care of all these issues. (eg all official docs on developerwiki, they have counterparts on public wiki. could we easily diff them? and "merge in" interesting changes (could by even manual copy paste work)
And, an arch-documentation package that is built by pulling the docs from trusted sources and packaging them. (install guides, beginners guide etc. this goes way beyond arch-releng)

Maybe even a "documentation team" ? some people who pull in changes from various sources into the official docs (community and devs/relengs themselves (any dev/releng can and should still keep his stuff up to date)), do some QA and release the docs package?
Comment by Aaron Griffin (phrakture) - Friday, 06 February 2009, 18:15 GMT
It's hard to build a documentation team, as no one likes doing it.

For right now, I'm just concerned with getting this page in a up-to-date state, and protecting it. If it's moved to the developerwiki, we can always change that later
Comment by Greg (dolby) - Friday, 06 February 2009, 18:25 GMT
AFAIK, the Guide doesnt necessarily need to be in the Developer wiki. It can be protected from worldwide editing in the normal section where users can use the discussion page. Maybe that would be even better.
Comment by Aaron Griffin (phrakture) - Friday, 06 February 2009, 19:00 GMT
Page is protected now. Check that one off the list - didn't know I could do that :)
Comment by Abhishek Dasgupta (abhidg) - Friday, 06 February 2009, 19:07 GMT
I've attached a diff with some corrections.
Comment by Xavier (shining) - Friday, 06 February 2009, 19:09 GMT
Here are my complaints :
1) this guide is huge and overly verbose
2) do we need to cover lilo? why not just support grub? I expect that someone having special reasons to prefer lilo over grub should be able to install it on its own.
3) I think the 3 first sections are important, and it ends with Internet access. Shouldn't it be the ultimate goal of this guide, getting a working system with internet access? All the rest is post install documentation. And once internet is working, the whole wiki becomes available for further documentations.

So about the 4th section on pacman :
1) it also looks unnecessary long. I think the most important ops for an install are : -Ss,-Si to look for packages, -S and -U to install.
2) -A is dead
3) why bother with long options everywhere? everyone uses short options

About the 5th section on ABS : is this really needed here? Seems post install material to me.
Comment by Aaron Griffin (phrakture) - Friday, 06 February 2009, 19:13 GMT
@Abhishek: Is this based on dolby's changes?

I think we should work from what dolby has, as he appears to have updated a decent amount, and it looks pretty good to me.
Comment by Eric Belanger (Snowman) - Friday, 06 February 2009, 19:13 GMT
There is this related bug:
 FS#6156  - Find translators for the installation guide
Comment by Xavier (shining) - Friday, 06 February 2009, 19:21 GMT
@Aaron: yes it is based on dolby's change. I mentioned pacman -A option being dead, and Abhishek fixed that.
I had a look at the other changes made by Abhishek and they all look very good to me.
Comment by Abhishek Dasgupta (abhidg) - Friday, 06 February 2009, 19:30 GMT
As Xavier said, it's based on dolby's git branch.
I tried to checkout the github repo but git gave an error
saying no references to HEAD.
Comment by Greg (dolby) - Friday, 06 February 2009, 19:34 GMT
Committed the patch. Thanks.
Dont take for granted that everything works as expected on my branch. They most likely dont :)
Comment by Aaron Griffin (phrakture) - Friday, 06 February 2009, 20:31 GMT
dolby, could you attach a git patch for this?
Comment by Greg (dolby) - Friday, 06 February 2009, 20:46 GMT
It will hopefully work
Comment by Greg (dolby) - Friday, 06 February 2009, 20:48 GMT
Use this one instead wrong patch! :/
Comment by Aaron Griffin (phrakture) - Friday, 06 February 2009, 21:22 GMT
@dolby: Feel free to add your credits to the top chunk too.
Comment by Greg (dolby) - Friday, 06 February 2009, 21:31 GMT
Not needed anymore :)
Comment by Greg (dolby) - Saturday, 07 February 2009, 12:37 GMT
"this guide is huge and overly verbose"
Would this http://wiki.archlinux.org/index.php/Official_Arch_Linux_Install_Guide , updated, be close to what you'd like instead?
Maybe i was wrong from the start, and a document like this may serve a purpose by staying only to the basics.
But even if thats so, if it gets inlcuded in ISOs it has to be less dependant on the wiki.
Comment by Greg (dolby) - Sunday, 08 February 2009, 08:41 GMT
I attached a streamlined guide. Its not fully up to date, and its based on the partly upgraded guide on my git branch and the official guide on the wiki i linked on my previous comment.
It follows the formatting of the guide on the ISO for the most part, i only increased limit to 80 chars. At this point its around 700 lines while the guide on the ISO is almost 2000.
Its missing some of the important changes in the to-be-released ISO. It still references hwdetect etc.
It has no references in pacman, ABS, lilo, or the FAQ the previous official guide had. But it might need further tweaking in order to be less verbose.
IMO it would be best at this point to decide what kind of guide would you like having.
The new ISO is around the corner. If you want it to be included, even if its not complete, it should at least be as much up to date as possible. All the available ATM guides are outdated when it comes to the new ISO.
Even the beginners guide. As always, any help & comments welcome.
Comment by Xavier (shining) - Sunday, 08 February 2009, 14:30 GMT
Dolby, since you are doing all the hard work, you are much more in position to decide what is best for the guide :) That is how things usually work in Arch.
That said, I had a look comparing the two guides you worked on, and I like the new one a lot, great work!
Maybe there could just be a few links at the end pointing to the wiki (eg the Beginners guide) for all the post install steps.
Comment by Abhishek Dasgupta (abhidg) - Sunday, 08 February 2009, 17:11 GMT
added some stuff to /etc/pacman.d/mirrorlist and
Set Root Password
Comment by Greg (dolby) - Sunday, 08 February 2009, 19:48 GMT
Some additional fixes. In case someone has used the RC ISOs adding stuff to Set Clock would great. Also any other changes in regards to the latest release.
Comment by Greg (dolby) - Sunday, 08 February 2009, 23:27 GMT
I consider this guide complete as far as getting stuff from the already available guides. Now all thats left to be done is to update it to the latest ISO release.
If anyone has any objections regarding what i chose to include from pacman options lets hear em. I decided ABS was outside the scope of this document.
Also the Boot Scripts part of the arch-install-guide.txt should be moved somewhere in the wiki if it isnt there already, or the beginners guide (if this guide will replace it). Its really nice.
It will probably take a couple of days, to perform installations and update the guide accordingly. Feel free to contribute.
Comment by Aaron Griffin (phrakture) - Monday, 09 February 2009, 17:07 GMT
I'd like to get a few head nods on this one - just a few people saying "looks good" before I go ahead and include it
Comment by Greg (dolby) - Monday, 09 February 2009, 18:26 GMT
I added pacman -Ss and -Si in the pacman section as they might be useful from the install environment. They were not part of the previous guide for some reason.
I started another git repo for this guide (which should work this time) http://github.com/grbzks/install-guide/tree/master . As i said before, this guide isnt updated to match the changes in the latest ISOs yet.
Comment by Aaron Griffin (phrakture) - Tuesday, 10 February 2009, 18:56 GMT
Ok guys - I am going to pull this into the installer repo, and release a new archlinux-installer package for the RC2 / final ISO release.

If there is anything pending, please say so now. You have approximately 1 hour :)
Comment by Aaron Griffin (phrakture) - Tuesday, 10 February 2009, 18:58 GMT
Whoops - dolby, can you remove "pacman" from the list of things under the Judd/Aaron copyright? Pacman is copyrighted by lots of different people, so probably shouldn't be mentioned there.
Comment by Greg (dolby) - Tuesday, 10 February 2009, 19:04 GMT
Done.
Comment by Greg (dolby) - Tuesday, 10 February 2009, 19:12 GMT
That reminds me, should i remove documentation from there too? Shouldnt it be under FDL instead? GPL is not a preper documentation license.
Comment by Aaron Griffin (phrakture) - Tuesday, 10 February 2009, 19:20 GMT
Well, we haven't officially licensed the documentation - that means that it is still copyrighted under the defaults of copyright coverage for a given country... it's annoying that way. I'm fairly certain we planned on using a CC license for documentation, but nothing official yet. So the code is GPL'd, documentation would be... just copyrighted. I'd say remove it for now
Comment by Aaron Griffin (phrakture) - Tuesday, 10 February 2009, 20:02 GMT
Suggestions:
* "minimum of 160MB of RAM" - I don't think this is the case. pacman actually works fine in a 32MB environment, if I recall. The kernel param ramdisk_size may need to be tweaked for smaller systems.

Confirming, just ram a VMWare install with 64MB of ram with no problems at all.

* The "Exit Install" section references the beginner's guide. Can we do away with that chunk? Maybe reference http://wiki.archlinux.org instead.
Comment by Greg (dolby) - Tuesday, 10 February 2009, 20:25 GMT Comment by Aaron Griffin (phrakture) - Tuesday, 10 February 2009, 20:35 GMT
Looks good to me.
Comment by Aaron Griffin (phrakture) - Tuesday, 10 February 2009, 22:14 GMT Comment by Aaron Griffin (phrakture) - Tuesday, 10 February 2009, 23:30 GMT
Changes are in the archlinux-installer 2009.02-2 package
Comment by Greg (dolby) - Wednesday, 11 February 2009, 19:20 GMT
Aaron just a note. I will be updating the file for as long as its needed, if i find anything wrong with it, or if someone suggests something worth adding (which hasnt happened yet).
If for any reason you update the installer scripts, check the doc too. Its already different than it was when you added it to the package. eg. md5sums-> sha1sums.
Comment by Dieter Plaetinck (Dieter_be) - Wednesday, 11 February 2009, 19:21 GMT
looks good (not that i checked thoroughly). the vim line at the bottom could maybe be removed though.
Comment by Aaron Griffin (phrakture) - Wednesday, 11 February 2009, 19:41 GMT
I like the vim line :)

@dolby: I added it as a branch to my local checkout, so I will merge in changes periodically.
Comment by Greg (dolby) - Thursday, 12 February 2009, 19:49 GMT
Also when the release is final make sure to update the http://wiki.archlinux.org/index.php/Official_Arch_Linux_Install_Guide , maybe latest git would be better.
Comment by Dieter Plaetinck (Dieter_be) - Friday, 05 March 2010, 18:56 GMT
I'm gonna close this ticket.
1) official installation guide is maintained in aif git
2) exports are done to the wiki pretty much everytime something is changed in the git version
3) the documentation has been updated by me a long time ago
4) beginners guide has no "official" in it, so i don't see a problem with it.

Loading...