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

[Heiko Baums]

Am Wed, 15 Jun 2011 12:26:21 +0200
schrieb Dieter Plaetinck <dieter at plaetinck.be>:

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

Why not? Where's the difference between maintaining one "Official
Install Guide" or one "Official Beginner's Guide"?

I never used the "Official Install Guide" because it's too confusing
and has too little details, while the "Beginner's Guide" is far more
detailed. So why not remove the "Official Install Guide" and maintain
the "Beginner's Guide" officially?

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

It's on the homepage of the wiki. And it definitely should stay there.

> 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.

If the "Official Install Guide" reflects the current state of affairs
the "Beginner's Guide" could easily do it as well.

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

That's not a solution as it makes it far more complicated for the user,
because then the user permanently had to switch between two guides
(websites) and would be forced to read the more confusing explanations
of the "Official Install Guide". This would be a big regression.

It's a lot better to have every information consecutively, detailed,
well formatted and with additional explanations in one text. This makes
it a lot easier particularly for (Arch/Linux) beginners.

The "Official Install Guide" e.g. doesn't explain anything about how to
partition the hard disk or what file system to use, etc. Such
additional infos belong into a "Beginner's Guide", but not into a
"Quick Install Reference".

> 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.

Couldn't both be done with the "Beginner's Guide", too? It could and
should be maintained in the wiki as a HTML document and could easily be
stripped down to plain text. And keep in mind that the formatting is
one of the most important parts which makes such a guide easy to
understand.

> > I would then link the guide in git from the new unified article.
> 
> this won't work, for the reasons described above.

I actually don't see a reason.

> 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.

The "Beginner's Guide" could be official, too.

> 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.

I disagree again, because "Beginner's Guide" tells the beginners that
this is the easiest point to start. And removing parts which are also in
the "Official Install Guide" makes it a lot more complicated
particularly for beginners.

> 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)

Less convenient for whom?

> 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.

I see that the "Official Install Guide" shouldn't be edited by any
user. But the "Beginner's Guide" could be closed for user commits, too,
even if I doubt that this would be that helpful.

I looked at both guides again, after a long time. And I would say the
best is to keep both.

The "Official Install Guide" should be kept as a "Quick Install
Reference" for more experienced users, what it in fact is, and the
"Beginner's Guide" as a more detailed install guide for less
experienced users and beginners.

Heiko