[arch-releng] ArchWiki: merge Official and Beginners' Guides? (or change titles)

[Dieter Plaetinck]

On Mon, 13 Jun 2011 18:09:26 +0200
Dario Giovannetti <dariogiova at alice.it> wrote:

> This discussion was started in 
> https://wiki.archlinux.org/index.php/Talk:Official_Arch_Linux_Install_Guide#Change_titles.3F_Official_vs_Beginners.27_Guide_.28formerly_.22Merge_with_Beginners.27_Guide.3F.22.29 
> 
> 
> What do you think of merging the Beginners' Guide and the Official
> Arch Linux Install Guide into a unified Installation Guide?

In principle, this would be preferable, in practice I don't think it's
possible because of various constraints. (see below)

> In my opinion having 2 separate installation guides on the wiki only 
> creates confusion for beginners who wonder why they are directed to
> an "unofficial" guide

I don't think we link to the beginners guide from anywhere. If we do,
let me know.

> This gets reinforced by the fact that the Official Guide is rarely 
> maintained

what do you mean? AFAIK it completely reflects the current state of
affairs (i.e. it's accurate for the latest official media), and if this
is not so, you should report this (and/or send a patch). It could be
expanded though (read on)
Sometimes I do changes to the guide but if the media are not official
yet, I wait with updating the wikipage until the new media are official.

> and almost if not all of its content is already
> duplicated in the Beginners' Guide.

Well that's obviously silly and adds duplication of work.
Solution -> remove duplications from beginners guide and refer to
installation guide.

> Also, wiki users tend to report bugs in the Official Guide in its
> talk page, instead of posting to the releng team.

that's a bit unfortunate, because the article is a bit exceptional in
how it is maintained (primary version in git, and the generated output
gets pushed to the wiki), but there is no better way because
1) we want to maintain the plaintext version to include it on our media
2) we don't want users to change official instructions. only
revised and accepted changes are allowed in the official guide.

> I would then link the guide in git from the new unified article.

this won't work, for the reasons described above.

> In alternative to all this, I'd propose to change the titles of the
> two guides to something like "Installation Tutorial" (or Guide) in
> place of the Beginners', and "Quick installation reference" (or
> Guide, or Notes) in place of the Official.

the official guide IS official and should be named as such. removing
that part will cause even more confusion.
It's true that it's a bit concise and could be expanded, but I would
prefer that people actually contribute improvements rather then
suggesting the title should include "quick" or "notes", because that's
not what it's meant to be.

A better solution IMHO might be to rename the beginners guide to
"Complete introduction to Arch Linux" or something, and remove all the
parts that belong in the official installation guide, rather refer to
them.



On Mon, 13 Jun 2011 15:46:15 -0400
Jeremiah Dodds <jeremiah.dodds at gmail.com> wrote:

> +1 from me, people who don't qualify as "beginners" (to linux) will
> just skip over extra information in the guide, and people who are
> will benefit from the simplification.

It's really not this simple.
If you put everything in one guide, that means many more contributions
will need to go through git, which is not desirable (because it's less
convenient)

Ideally, the wiki would use a git backend and provide an easy interface
to submit, preview and validate contributions. that would combine all
the requirements (quality review, plaintext version, commits in aif
git can comprise changes to both code and the guide, and ease of
contributions because of the wiki UI) but that's not how it is...
Storing the official guide in the wiki is not possible because of
reasons mentioned above.


Dieter