Am Wed, 15 Jun 2011 12:26:21 +0200 schrieb Dieter Plaetinck :

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

On Wed, Jun 15, 2011 at 1:43 PM, Dieter Plaetinck wrote:

for anyone who tries to contribute. the git workflow just is more cumbersome (you need to fork, fix, make a patch and mail it, or publish code, do a pull request, etc)

As far as I can tell, that's a pretty uncommon opinion, or rather even if it is "more cumbersome", it tends to *encourage* contribution as opposed to otherwise. Github is hugely successful, for instance. I can't imagine many people finding it much more cumbersome than figuring out how to make a contribution to, well, any project.

On Wed, Jun 15, 2011 at 6:26 AM, Dieter Plaetinck wrote:

On Mon, 13 Jun 2011 18:09:26 +0200 Dario Giovannetti wrote:

On Mon, 13 Jun 2011 15:46:15 -0400 Jeremiah Dodds 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)

Forgive my ignorance, but how would this mean that many more contributions would have to go through git? Also, less convenient than what?

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.

Make the official guide it's own git repo, use it as a submodule in aif, and set up a hook to wikify / unwikify as appropriate? That's an out-of-the-ass idea though, I'm not currently familiar enough with Arch's setup in terms of repos and where everything is coming from to know if that's a good, let alone viable or shortest-path solution. On Wed, Jun 15, 2011 at 7:19 AM, Heiko Baums wrote:

Am Wed, 15 Jun 2011 12:26:21 +0200

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. I think this is also a decent idea, the main goal should be to remove ambiguity as to what guide people, especially newbies, should be looking at.

In my opinion, there is no reason to keep the official guide on the wiki: wiki formatting and templates are not utilized, we do not benefit from the wiki's version control system, and effort is wasted syncing the wiki with the version in git. Rather, users are confused and suggest corrections/improvements on the wiki when they should use this mailing list or the bug tracker. The easiest change to make towards a better solution, in my opinion, is to remove the official guide from the wiki and simply link to the version in AIF git on the Main Page (and www.archlinux.org home page) and from within the Beginners' Guide itself. Furthermore, the Beginners' Guide should be renamed because it is misleading; perhaps Gentoo users would understand the official guide, but even seasoned Ubuntu veterans would probably learn something from the Beginners' Guide (please excuse my stereotyping!) "Unofficial Installation Guide" or "Detailed Installation Guide" or "Installation Walkthrough" would be more appropriate. Merging guides, and/or the rationale for maintaining two installation guides can be discussed in-detail later. (It is unlikely a consensus will be reached, though... evidenced by the existence of several other installation guides (https://wiki.archlinux.org/index.php/Quick_Arch_Linux_Install; https://wiki.archlinux.org/index.php/Installing_with_Software_RAID_or_LVM; and other pages under https://wiki.archlinux.org/index.php/Category:Getting_and_installing_Arch_(E...). Can we constrain this discussion to the renaming of the Beginners' Guide for now? -- Des On Mon, Jun 13, 2011 at 3:46 PM, Jeremiah Dodds wrote:

On Mon, Jun 13, 2011 at 12:09 PM, Dario Giovannetti wrote:

...

This discussion was started in https://wiki.archlinux.org/index.php/Talk:Official_Arch_Linux_Install_Guide#...

What do you think of merging the Beginners' Guide and the Official Arch Linux Install Guide into a unified Installation Guide? 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, and is of no help for experienced users. This gets reinforced by the fact that the Official Guide is rarely maintained, and almost if not all of its content is already duplicated in the Beginners' Guide. Also, wiki users tend to report bugs in the Official Guide in its talk page, instead of posting to the releng team. I would then link the guide in git from the new unified article.

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.

Dario

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