Difference between revisions of "Talk:Beginners' guide"

From ArchWiki
Jump to: navigation, search
(Adding a User section...: new section)
(Splitting into sub pages: new section)
Line 135: Line 135:
  
 
Wouldn't it be easier, and more user-friendly, to just invoke the adduser command? It's like useradd, but interactive. That way we can get rid of a chunk of that section (describing the options of useradd) since most of the interactive options of adduser are self-explanatory... Remember, this isn't a guide in which we should teach the user what the options of every command. That's what the man pages and other wiki articles are for... --[[User:Xgamer99|Xgamer99]] 20:59, 9 January 2011 (EST)
 
Wouldn't it be easier, and more user-friendly, to just invoke the adduser command? It's like useradd, but interactive. That way we can get rid of a chunk of that section (describing the options of useradd) since most of the interactive options of adduser are self-explanatory... Remember, this isn't a guide in which we should teach the user what the options of every command. That's what the man pages and other wiki articles are for... --[[User:Xgamer99|Xgamer99]] 20:59, 9 January 2011 (EST)
 +
 +
== Splitting into sub pages ==
 +
 +
I just migrated all the data to different sub-pages as discussed [[#To_split_or_not_to_split.3F|here]]...
 +
 +
The pages are designed in such a way that all of the content resides on the sub pages and are linked to (included) from the main [[Beginners' Guide]] page. This creates the illusion of a complete, and lengthy, one-page guide for those who prefer it. This should make everyone happy. =D It also creates pages for those who prefer that. Note that the content is '''not''' copied, but instead is linked, like templates. This means that two copies of the same thing are not maintained -- change the source, and you change both the 'complete' and 'paged' views.
 +
 +
Editing is much the same also. If you traditionally use the in-article [edit] links, you'll be presented with the text from the sub page seamlessly. If you edit via the Edit button at the top of the page, then you must go to the sub page itself and edit it (since the main page will have no content to edit).
 +
 +
One thing to note is how to use anchor tags between sub pages. If you're editing, say, the "About This Guide" section where it links to the major sections of the guide, you need to take into consideration that the reader might either be a) reading it from the 'complete' page, where the link would only need to be #PageAnchor, or b) reading it on the different sub pages in which case it will need to be linked like so: Beginners' Guide/PageName#Section. The easiest way to do this is to use the <nowiki><noinclude></nowiki> tag like so: <noinclude>Beginners' Guide/PageName</noinclude>#Section. That way, if the reader is reading the entire guide on one page, the Beginners' Guide/PageName will not be included. But if the user is directly on the seperate sub pages, it will be included. '''Please''' keep both 'complete' and 'page' viewers in mind when linking to information located on different sub pages. Also, please note that this does not matter on info located on the same page; it can still be linked to via the regular #Section syntax.

Revision as of 07:59, 12 January 2011

  1. The Beginners Guide now redirects to Beginners' Guide.
  2. A version bump in mediawiki has rectified the former apostrophe bug which rendered the page useless.
  3. Please make all editing suggestions here.
  4. Please keep discussions civil and productive.

Thanks. Misfit138 15:23, 22 October 2009 (EDT)

Suggestions

About 2.9.3 - /etc/fstab

  • I think the possibility of using tmpfs for /tmp should at least be mentioned and possibly even encouraged.
  • Only the noatime option is mentioned, what about its big brother nodiratime and its safer cousin relatime ? Maybe a note about that in the Arch installer-generated /etc/fstab would be good too. See http://kerneltrap.org/node/14148 for details.

Changaco 08:13, 25 October 2009 (EDT)

A simple, lightweight Beginner's Guide

One of the things my professor kept (h/y)ammering about when it came to software documentation was the difference between "data and information". The important thing in this context he always said was unambiguity: use a single example to show the 'way of doing things'. This makes a lot of sense, since the intention isn't to provide choice, but to provide information on how things work so people can make their own choices.

Extrapolating this to our BG, i think it would be a good idea to start using single examples of how stuff works on Arch. For instance, we can take Xfce or Lxde and show how it is group-installed, this will help people who just want a working Arch up and running. Other DE's and WM's should be linked-to only, give a small explanation of the different options and where installation instructions can be found. It is really not necessary to provide almost-identical-but-slightly-different installation intructions for 5-6 graphical desktops in the BG, it is confusing the people who really need beginner's instructions. Another argument for this is the Occam's Razor principle: don't duplicate efforts, KDE & Gnome etc. already have their own wiki pages with detailed installation instructions. Keep the BG simple and focused and people will understand better 'where to find what'.

Areas where i would propose to take the above approach:

  1. Graphical desktop (DE/WM etc.)
  2. Proprietary video (use xf86-video as preferred example, link to FGLRX/NVIDIA pages for vendor lock-in alternatives)
  3. Filesystems (use EXT as example, link to page with info on other filesystems)

Other sections that could definitely be moved out of the official BG to a separate wiki page:

  1. Analog modem/ISDN (for the 0.1% installing Arch on analog modem, a link to the appropriate page will suffice)
  2. Third party (openntpd/powerpill/? - they're handy tools, but definitely not essential for installation)
  3. Manual xorg.conf (X is moving away from this, it's not the preferred way anymore. Provide link for people who need it)
  4. Font configuration (the system will work fine without custom fonts, not BG material; if you want fancy fonts, read the designated wiki page)

Your opinions on this? I will be more than happy to help abstracting the above sections and work towards a simple, lightweight Beginner's Guide. litemotiv 04:45, 7 December 2009 (EST)

I feel the need to mention that using "a single example to show the way of doing things" does not apply in this context. It's not just any kind of information; it is instructional. This reasoning is apt for narration, not manuals. Having said that, I agree with all of your suggestions, specially the ones on repeating content from GNOME, KDE, etc. One striking peculiarity about these sections in the Beginners' Guide is how they are potentially conflicting ones, assuming that installing KDE in parallel to GNOME is a rare course of action. Partially coinciding with your observation: other sections are escalating, these are forking. Time 07:45, 7 December 2009 (EST)
I agree with Time. I would like to keep the instructional nature of the guide intact at the cost of repetition. I also agree with these points:
  1. Analog modem/ISDN (for the 0.1% installing Arch on analog modem, a link to the appropriate page will suffice) agree
  2. Third party (openntpd/powerpill/? - they're handy tools, but definitely not essential for installation) agree -- provide links
  3. Manual xorg.conf (X is moving away from this, it's not the preferred way anymore. Provide link for people who need it) agree -- mention this exact fact and provide link(s)
  4. Font configuration (the system will work fine without custom fonts, not BG material; if you want fancy fonts, read the designated wiki page) ? which section are you referring to?
Misfit138 12:34, 7 December 2009 (EST)
I think the instructional approach is fine, my 'single example' suggestion was meant as a possible way of providing a fully working Arch desktop for beginners without giving redundant installation instructions for alternatives (e.g. desktop environments). In this way one could just follow all the commands from top to bottom and end up with a working example-installation, every command would be a unique step in the process. With this approach no decisions need to be made, but can be if one desires so (show the commands to install example-DE and give links to the other DE-pages). There is a risk of politics here obviously, since we'd need to choose an example package for each section.
The alternative of primarily explaining procedures when choices need to be made (like the aforementioned desktop environment) might also work, we should think about this and maybe create a test-page like Thisoldman proposes. It would be interesting to see if choice-intensive sections like DE/video work without any direct instructions at all.
@4 above: Part IV - Step 1; i would say that the existing link to Font Configuration is fine, we could just remove the installation text/commands above it (provide only commands for essential tasks) - Litemotiv 16:49, 9 December 2009 (EST)
Small correction to my previous message: a history lesson is both narrative and instructional. A more accurate discription would've been procedural, instead of calling it merely instructional. Time 16:23, 7 December 2009 (EST)
I agree with litemotiv. To be clear, however, we should always provide choice. But we need never tell anyone how to make their choice.
As I have mentioned before, all wikis need to implement XOXO so that we can have a more useful, collapsing outline layout. This keeps things simple, yet allows a depth of information that saves a lot of unnecessary page loading and reloading when only links are used. It is also far superior to any other method because the user can collapse all but the currently important areas to keep the install process simple and clear as she or he goes along.
In any case, the elimination of duplicate text is a huge benefit. In fact we could take it a little further and explain in general terms what these various sections are for, such as the DE choice, and then give the links to, first of all, a wiki page of comparison, and second, an individual wiki page for the installation of each one, but only from the comparison page. There is no need for any how-to in any of those areas of the BG; rather it is enough to point out that this is the point in the install process to add one if so desired. We don't even need a sample install; that goes in the appropriate wiki page for that item.
Also, I have found that a streamlined and simple install keeps the user from getting bogged down in unfamiliar minutia that has no bearing. If something can be installed at a later time, after the system is up and running, then it should be left out of the install, or placed in the addendum. Including something here clearly implies one should address it now. That is often just not true.
It is easy to get involved in details simply because someone else started down that path. I have been guilty of falling into that trap, and the simplification idea would go a long way in protecting all of us and keeping us on track. It appears prudent to re-evaluate the route from start to finish before starting the journey down it yet once again. - KitchM 20:59, 7 December 2009 (EST)
This is another good point, many sections of the BG are written verbose with unnecessary background information. For instance, the section about Pacman can be compressed back to this:
Now we will update the system using Pacman. Pacman is the package manager of Arch Linux, we will use it to download software packages and install them onto our system.
This saves us about 20 lines about how Pacman is written in C and how it uses gzip instead of bzip etc. We should take a careful look at each section and try to eliminate any smalltalk or superfluous information.
- Litemotiv 04:50, 10 December 2009 (EST)
Yes. Good point. There seems to be a lot of that thru-out the wiki, but sometimes a person may be a little concerned about editing someone's verbiage. If we can all agree on removing such things, we can feel a little more at ease about going thru and fixing articles. Also, there is still the question that remains up in the air and unaddressed; "Who is the target of the articles". If it is strickly for the intermediate or advanced user, then the tone of the articles may actually allow such extra, "techie" stuff. - KitchM 13:52, 10 December 2009 (EST)
~ I agree. The article lacks clarity. Information is presented in the Beginners' Guide that belongs elsewhere or should be eliminated entirely. Do we need 5 introductory sections before the reader is told to download the software?
Will anyone dare to take a first stab at this drastic edit and post the draft somewhere?
Sidenote—I appreciate that people are trying to keep the tone formal, but this has led to multi-syllabic obfuscation. We need to remember our reader may have limited English language skills.
--Thisoldman 07:35, 8 December 2009 (EST)
Just a newbie here. I have now gone through the install four times following the beginner's guide. From my perspective, I'd like to see it evolve more along the direction of a branching flow chart than a serial progression of tasks, many of which are specialized/optional. This already exists to some degree, but it could be improved. Something I had to discover on my own was the laptop wiki page. Having a link at an appropriate point in the beginner's guide, eg. "If you are installing on a laptop, consider the modifications described on this page" would be nice. This is just an example of how easy it is to make a new user aware of different options available in the construction of a new system with just one new sentence in the document. Clearly denoting optional, non-essential components would also be very useful.
We have the appendix at the bottom that links here, but it's probably not prominent enough. thestinger 12:40, 13 December 2010 (EST)

ntfs-3g

I have seen posts in newbie corner that could be solved by just mentioning ntfs-3g in some appropriate place in the beginners guide or in the General Recommendations/appendix. --Singenbale 09:26, 18 December 2010 (EST)

To split or not to split?

Also inspired from #A simple, lightweight Beginner's Guide...

I would like to see the Beginners' Guide split into a series of separate articles. This would serve to facilitate maintenance, primarily. The page already outlines four parts apt to be split into separate articles. I envision:

  1. Beginners' Guide (essentially, the "Preface" section as it currently stands and "Appendix" at the end)
  2. Beginners' Guide/Part 1: Base Install
  3. Beginners' Guide/Part 2: Configure and Update
  4. Beginners' Guide/Part 3: Sound
  5. Beginners' Guide/Part 4: Graphical User Interface

Additionally, a "complete" version of the guide could be generated at Beginners' Guide/Complete that simply includes all four parts in succession using the {{}} markup. This version would be intended for those printing the guide.

Ideally, I think Part 1 should eventually redirect to the Official Arch Linux Install Guide. I see no need to maintain two installation guides. However, this is an entirely separate discussion.

Thoughts?

-- pointone 14:39, 2 December 2010 (EST)

I appreciate the effort at making the best of a situation. Without a collapsing outline mechanism, the splitting out of the sections into separate articles may be useful. However, at the end of each one, the user needs a large link to get them back to where they started, so that they can continue on with the next step in the install. - KitchM 19:56, 2 December 2010 (EST)
I think it could be a good thing, although I fear that it could ultimately become inconvenient and convoluted. One of the things that has kept the guide so popular and well-regarded is its existence as being self-contained. *Note that there is virtually no negative press on the web about the guide in its current state.* A 'beginner' would simply need to follow it step-by-step and in most cases never need to follow links in order to achieve a relatively complete DE system. At the opposite extreme would be something like the Debian wiki, which exists as innumerable little pages with 'Next Top Previous' et all. I find the Debian wiki to be unruly and a big mess. So, my input is be wary of the guide spiraling into fragmentation, which in my view will render it convoluted and harder to grasp, especially for a beginner. Progress and improvement is always welcomed. Change, however, is not always positive. I truly hope it actually turns out to be an improvement. -my $.02 Misfit138 12:32, 3 December 2010 (EST)
I appreciate your concern, and I too am wary of the Debian "step-by-step" style installation guide. However, ArchWiki has matured immensely since the Beginners' Guide was originally written and designed. Before, many supplementary articles did not exist or were of inferior quality. Now, however, we enjoy a wide range of well-written, detailed articles covering a respectable number of topics.
I believe it is time to rethink the goal of the Beginners' Guide. What is its purpose and intended audience?
  1. To cover all aspects of installing and configuring Arch Linux? Then it certainly fails in this respect, and needs much expansion. (For example, it doesn't even explain how to install OpenOffice! Who decided that audio/sound deserves mention here but not printing?)
  2. To simply guide new users through installation of a basic Arch Linux system and configuring a graphical environment? Then we're close, but there is some unnecessary cruft here.
In my opinion, this guide should serve to bring users to the point where they can browse the rest of ArchWiki in a comfortable graphical environment (that is, Xorg + web browser). Then, they are free to pick-and-choose which extra components they wish to install and follow detailed (dedicated) guides on each. After all, are Arch Linux users not expected to search the wiki/forums first for help?
My primary concern is, and always has been, duplication of effort. The recent flood of edits required by the drastic changes in recent versions of Xorg is an excellent example of why maintaining two Xorg installation guides is problematic. By splitting the Beginners' Guide, we can eventually replace the GUI section with selected sections of a well-written Xorg article using available wiki tools (includeonly/noinclude are not reserved for templates alone). Similarly, as I mentioned above, the installation section can eventually be replaced by a drastically improved Official Arch Linux Install Guide (this is a very long-term goal). With careful consideration and planning, I am sure these changes will be positive in the long-term.
-- pointone 13:54, 7 December 2010 (EST)
Yes, pointone, I agree fully and am all for progress and improvement, and your reasoning is sound. I'm also very happy that I am not the only one afraid of the Debian-style wiki threat. Thank you for acknowledging this. I have beaten this drum around here for years. Misfit138 11:08, 8 December 2010 (EST)
Splitting the article might be a good idea, but I don't like the idea of graphics being covered in two different articles, so I'm going to do what makes sense - move installing Xorg to the GUI section (basically just have to move the part 4 header). This also makes me wonder why we cover sound here and not in a Sound article instead - which would let us give people more choice between ALSA and OSS, and also let us mention PulseAudio and JACK for people who want them on top of ALSA/OSS. Sound isn't required for people to have a GUI web browser/text editor that they're comfortable with, which seems to be the purpose of this guide. thestinger 13:55, 3 December 2010 (EST)
The ALSA article has also improved quite a bit, and it will probably work for more people than the sound section here, which doesn't even cover alsaconf. It's sort of similar to how the DE articles improved to the point that they were easier to follow than this guide thestinger 14:01, 3 December 2010 (EST)
I am all for the creation of a survey Sound article. Allowing Multiple Programs to Play Sound could serve as the base (it desperately needs clean-up and expansion). I don't think sound deserves coverage in the Beginners' Guide, really. -- pointone 14:15, 9 December 2010 (EST)
The Allowing Multiple Programs to Play Sound article was basically 99% ALSA related troubleshooting or plugs for dead software (joss, oss2jack, aRTS, esound) so I merged most of it into the ALSA and just started a basic outline for Sound from scratch. thestinger 16:52, 9 December 2010 (EST)

4.1 Configuring the network

Most of this section is a repeat of info already presented earlier in the guide (most notably in 3.1.1).

I understand that directing users to 3.1.1 when they've already got a system up and running isn't that great of an idea since they are no longer in the live environment and some things are different (but not much!), but surely something can be done to reduce the redunancy (especially on the 4.1.2 Wireless LAN section, which is basically a 1:1 copy of 3.1.1.2) Xgamer99 19:49, 8 January 2011 (EST)

Went ahead and made the edit, as I can't see anything wrong with it. Please let me know if you disagree. However, I still believe that 4.1 should be re-worked and merged with 3.1.1, and just have 4.1 direct users to it. The only thing that would need to be added is the Proxy settings and manual wired connection (installer handles wired connections flawlessly, so manual activation isn't covered in 3.1.1). Xgamer99 04:00, 9 January 2011 (EST)

Adding a User section...

Wouldn't it be easier, and more user-friendly, to just invoke the adduser command? It's like useradd, but interactive. That way we can get rid of a chunk of that section (describing the options of useradd) since most of the interactive options of adduser are self-explanatory... Remember, this isn't a guide in which we should teach the user what the options of every command. That's what the man pages and other wiki articles are for... --Xgamer99 20:59, 9 January 2011 (EST)

Splitting into sub pages

I just migrated all the data to different sub-pages as discussed here...

The pages are designed in such a way that all of the content resides on the sub pages and are linked to (included) from the main Beginners' Guide page. This creates the illusion of a complete, and lengthy, one-page guide for those who prefer it. This should make everyone happy. =D It also creates pages for those who prefer that. Note that the content is not copied, but instead is linked, like templates. This means that two copies of the same thing are not maintained -- change the source, and you change both the 'complete' and 'paged' views.

Editing is much the same also. If you traditionally use the in-article [edit] links, you'll be presented with the text from the sub page seamlessly. If you edit via the Edit button at the top of the page, then you must go to the sub page itself and edit it (since the main page will have no content to edit).

One thing to note is how to use anchor tags between sub pages. If you're editing, say, the "About This Guide" section where it links to the major sections of the guide, you need to take into consideration that the reader might either be a) reading it from the 'complete' page, where the link would only need to be #PageAnchor, or b) reading it on the different sub pages in which case it will need to be linked like so: Beginners' Guide/PageName#Section. The easiest way to do this is to use the <noinclude> tag like so: Beginners' Guide/PageName#Section. That way, if the reader is reading the entire guide on one page, the Beginners' Guide/PageName will not be included. But if the user is directly on the seperate sub pages, it will be included. Please keep both 'complete' and 'page' viewers in mind when linking to information located on different sub pages. Also, please note that this does not matter on info located on the same page; it can still be linked to via the regular #Section syntax.