[arch-dev-public] [arch-general] Official Installation guide needs your help!

[Tom K]

Aaron Griffin wrote:
> On Fri, Feb 6, 2009 at 3:12 PM, Grigorios Bouzakis <grbzks at gmail.com> wrote:
>   
>> On Fri, Feb 06, 2009 at 03:33:49PM -0500, Dusty Phillips wrote:
>>     
>>> 2009/2/6 Aaron Griffin <aaronmgriffin at gmail.com>:
>>>       
>>>> Hey guys,
>>>> I wanted to make you aware of the following:
>>>> http://bugs.archlinux.org/task/13140
>>>>
>>>> The "Official Installation Guide" is severely outdated (the wiki page
>>>> still mentions "i686 optimized").
>>>>         
>>> As one of the two people who was once on Arch's only attempt at an
>>> official documentation team, and as one of several people who
>>> contributed many of the first articles to the wiki, I have this to say
>>> on the topic:
>>>
>>> Drop the official install guide.
>>>
>>> We know our wiki is well-maintained and well organized, and it seems
>>> to do that by itself without much developer interference. Go wiki!
>>> Originally, when we first set the wiki up Dennis, Judd, and I felt
>>> that the official install guide should be more... well... official.
>>> But its out of date, its always out of date, and there are wiki texts
>>> that are not out of date. Now, seeing how our wiki experiment has
>>> exceeded our hopes and expectations,  I'd say that the install guide
>>> (drop the 'official') should be community maintained as are all our
>>> wiki pages. It will improve. When its time for a release, "somebody
>>> official" should read through it, ensure its accurate, convert it to
>>> plaintext and put it on the iso.
>>>
>>> Dusty
>>>       
>> I agree with the above for the most part. The only "problems" with the
>> Beginners Guide, which is the only up to date and worth of being
>> included anywhere guide is that its too "wikified". eg. references
>> "go here" with a link to another wiki page. It would definately take
>> less time to convert it into something less dependant on the wiki than
>> refactoring the official guide.
>> Also theres references to eg. like Loui said yaourt which should
>> probably go (?)
>> Also the official guide is linked from all over the place. archlinux.org
>> wiki.archlinux.org + its part of the iso. Should those change to link
>> the beginners guide? Should the Beginners Guide change its name to the
>> Arch Linux Handbook for example?
>> FTR I had always been in favour of maintaining 1 guide from the beginning.
>>     
>
> I'm for changing the name to "Arch Linux Handbook" and maintaining one
> guide. It seems simpler. But we should take care to include references
> to unofficial tools and things somewhere else - i.e. the "install
> yaourt" stuff
>
>   

The name doesn't really matter. IMO anything we include on the official
ISO becomes official documentation by default. In that context, I
believe we should retain a simple how-to-install-Arch-core doc, with
clear direction for users regarding where to go next i.e. the wiki. In
other words, +1 for Xavier's suggestion in the bug report - a bare-bones
install guide consisting of revised sections 1-3 and a very brief Pacman
overview.

I have a problem with the Beginner's Guide as official documentation, as
I don't believe it gives an accurate first impression of Arch. It is not
compatible with Arch core principles, IMO, although I accept that it has
established itself as a useful community-provided resource. I have
already mentioned these reservations to Misfit, btw.

I'll have a look over dolby's latest revision, and if I have additional
suggestions, post them in the bug report.

T.