[arch-releng] ArchWiki: merge Official and Beginners' Guides? (or change titles)
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
On Mon, Jun 13, 2011 at 12:09 PM, Dario Giovannetti <dariogiova@alice.it>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.
On Mon, 13 Jun 2011 18:09:26 +0200 Dario Giovannetti <dariogiova@alice.it> 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 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@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
Am Wed, 15 Jun 2011 12:26:21 +0200 schrieb Dieter Plaetinck <dieter@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
On Wed, 15 Jun 2011 13:19:06 +0200 Heiko Baums <lists@baums-on-web.de> wrote:
Am Wed, 15 Jun 2011 12:26:21 +0200 schrieb Dieter Plaetinck <dieter@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?
beginners guide is very broad and is cumbersome / time consuming to maintain officially. * officially means releng has to approve, and devs in releng already have a huge time shortage, i don't want to spend my time approving and discussing tidbits of info outside my scope (i.e. the stuff found in the beginners guide). * as for cumbersome / time consuming, see next point
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?
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)
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.
and it accurately describes both the beginners guide and the official install guide. if users still find it confusing, maybe we could expand the accompanying text a bit more.
would be forced to read the more confusing explanations of the "Official Install Guide".
well, contributions are welcome...
On Wed, Jun 15, 2011 at 1:43 PM, Dieter Plaetinck <dieter@plaetinck.be>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, 15 Jun 2011 18:17:24 -0400 Jeremiah Dodds <jeremiah.dodds@gmail.com> wrote:
On Wed, Jun 15, 2011 at 1:43 PM, Dieter Plaetinck <dieter@plaetinck.be>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.
Well, don't forget we're talking about contributing typo fixes, or a few lines of text. The git thing IS an overhead AND confuses people because it's not what you expect on the wiki. Dieter
On Wed, Jun 15, 2011 at 6:26 AM, Dieter Plaetinck <dieter@plaetinck.be>wrote:
On Mon, 13 Jun 2011 18:09:26 +0200 Dario Giovannetti <dariogiova@alice.it> wrote:
On Mon, 13 Jun 2011 15:46:15 -0400 Jeremiah Dodds <jeremiah.dodds@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)
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 <lists@baums-on-web.de> 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.
Il 15/06/2011 13:19, Heiko Baums ha scritto:
The "Beginner's Guide" could be official, too.
First of all I'd like to clarify that my original idea was not to have the releng team officially maintain the unified guide. I was thinking of keeping the official guide only in git, and having only a wiki-maintained, more-detailed guide (the current beginners') in the wiki: this guide should be (and already is) based on the official guide, which in turn should be linked from the guide in the wiki itself.
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 would strongly oppose on protecting the Beginners' Guide: if it's that much detailed and clear it's because many normal users have contributed freely to improving it over time. Let's not forget that as there are many people editing it, there are also many who constantly check that it's not vandalized or wrong content is added. Let's trust the community.
Il 15/06/2011 12:26, Dieter Plaetinck ha scritto:
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. The rc.conf section is the main example of the outdating of the official guide, especially for people installing from the net install image, who get an up-to-date initscripts package, among the others. this won't work, for the reasons described above. A link to the guide in git won't work? The reasons you described don't really explain why, and I don't see so many problems in creating a link.
Dario
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_(English)>). 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 <jeremiah.dodds@gmail.com> wrote:
On Mon, Jun 13, 2011 at 12:09 PM, Dario Giovannetti <dariogiova@alice.it>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.
Am Thu, 16 Jun 2011 00:24:14 -0400 schrieb Desmond Cox <desmondgc@gmail.com>:
Can we constrain this discussion to the renaming of the Beginners' Guide for now?
Then both should be renamed: "Official Install Guide" -> "Quick Install Reference" "Beginner's Guide" -> "Install Guide" That said, I don't think that "Beginner's Guide" is so misleading. In my opinion the name "Official Install Guide" is rather misleading. And the word "official" is in fact not needed. I don't think that merging or making big changes to both guides is necessary and useful. Heiko
participants (5)
-
Dario Giovannetti
-
Desmond Cox
-
Dieter Plaetinck
-
Heiko Baums
-
Jeremiah Dodds