1 |
Duncan wrote: |
2 |
> [much rambling] |
3 |
|
4 |
> This is a followup from |
5 |
> http://linux.slashdot.org/comments.pl?sid=236711&cid=19324981 |
6 |
> and (beware the wrap) |
7 |
> http://www.funtoo.org/drobbins/blog/2007/05/gentoo-linux-20070-review- |
8 |
> first.html |
9 |
> |
10 |
> Nightmorph mentioned posting comments in regard to the documentation |
11 |
> angle here, so here I am. I've been lurking and don't /think/ I'm |
12 |
> rehashing old discussions, but if so, just tell me. Anyway, repeating |
13 |
> the comment I made in the link, so folks don't have to go read it of they |
14 |
> don't want to... |
15 |
> |
16 |
> In trying to reply to the issues as I did, well, let's just say I'd have |
17 |
> been confused trying to read the present install documentation as a |
18 |
> Gentoo newbie (it was confusing enough as it was, knowing what was in the |
19 |
> old handbook and trying to see if it was in the current one, then finding |
20 |
> there was a 2007.0 one as well). It can be sorted out, but it's not |
21 |
> easy, and whats worse, with both a 2007.0 handbook, and a general Gentoo |
22 |
> Linux handbook, if someone goes for help and refers or is referred to the |
23 |
> handbook, it's quite possible the person wanting help and the person |
24 |
> trying to help will each be reading different "handbooks", and not even |
25 |
> realize it until much confusion has ensued. |
26 |
> |
27 |
> - For 2007.1, full integration of the old Gentoo Handbook into the new |
28 |
> Gentoo 2007.x handbook should be complete, so there's only one "handbook" |
29 |
> and people won't get confused. It looks like it was already headed that |
30 |
> way, but unfortunately hadn't been completed. Probably trim the parts |
31 |
> other than installation from the old one as they appear to be in the new |
32 |
> one already, and retitle the remaining installation "Manual |
33 |
> Installation", or "Installation without the installer" or something |
34 |
> similar. |
35 |
> |
36 |
> - Modify the existing Installation Documentation listing |
37 |
> ( http://www.gentoo.org/doc/en/index.xml?catid=install ) or create a new |
38 |
> one suitable to be the primary installation documentation landing point. |
39 |
> Off the top of my head, that means moving the Installation Related |
40 |
> Resources up, eliminating or condensing and possibly moving to the bottom |
41 |
> the intro and doc repository paragraphs. |
42 |
> |
43 |
> - Further modifying the Installation Docs listing, reorder the list so |
44 |
> commonly needed resources are at the top. Leave the handbook first (but |
45 |
> as I said, make sure there's only one "handbook", or at least deprecate |
46 |
> and move a second one down under "Other", if it continues to exist), |
47 |
> followed by the quick-install guide, tips and tricks, and alternate |
48 |
> install methods. Only those four under the first/main header. |
49 |
> Everything else under "Other Related". |
50 |
> |
51 |
> - Consider making all four entries in the main install section language/ |
52 |
> arch-landers of their own, much as the two handbooks are already |
53 |
> handled. Thus, the quick install guide link on the main lander will link |
54 |
> a (generic) quick install guide lander, which would in turn have the |
55 |
> existing x86, sparc, and gfbsd guides, among others. The G/amd64 FAQ and |
56 |
> chroot howtos, currently linked from the amd64 project, may be possible |
57 |
> candidates for linking on the tips and tricks lander. The LVM2, GRUB |
58 |
> error collection, USB, and Bluetooth guides may fit here as well, as may |
59 |
> the MIPS guide. Of course, if this is done, the descriptions for quick |
60 |
> install and tips on the main installation lander page would need expanded |
61 |
> to mention them, as appropriate. |
62 |
> |
63 |
> - Gentoo 1.4 upgrade could probably by now be removed or moved to a |
64 |
> "deprecated" lander. The 2.6 kernel upgrading guide may need to hang |
65 |
> around for awhile, but could be moved to either the deprecated lander |
66 |
> with G/1.4 or an upgrade lander, with the Gentoo upgrading guide. |
67 |
> |
68 |
> - Other possible landers if an alternate organization is chosen might |
69 |
> include hardware (bluetooth, USB, MIPS, etc) and system software landers |
70 |
> (GRUB, kernel 2.6 upgrading and genkernel guides, etc). |
71 |
> |
72 |
> - Given the studies demonstrating a dramatic drop in usability and |
73 |
> simplicity when the number of choices exceeds 4-7, (coincidentally or |
74 |
> not, seven is said to be the number of "memory elements" an average |
75 |
> person seems to be able to hold in active instant memory at once, before |
76 |
> things start dropping out), if we could reduce the number of immediate |
77 |
> choices on the main Installation Documentation lander page to seven or |
78 |
> less, using secondary landers as suggested above, I believe it would |
79 |
> dramatically increase the usability of such a lander page. Thus, that'd |
80 |
> be a worthwhile goal, IMO. |
81 |
> |
82 |
> After fixing up the main installation docs lander page: |
83 |
> |
84 |
> - In all installation documentation other than the single Installation |
85 |
> Docs lander, replace the possibly many references to related install |
86 |
> documents with a single (or single per chapter anyway, in the case of the |
87 |
> old/manual method handbook, given the length) but likely higher |
88 |
> prominence reference to the Install Docs main lander. This will simplify |
89 |
> wording in multiple resources, while pointing all readers at the single |
90 |
> common installation docs landing point, with the benefits that brings in |
91 |
> terms of consistent and maintainable documentation. |
92 |
> |
93 |
> |
94 |
> If this is done, I believe it will make finding the proper documentation |
95 |
> easier and less confusing, and therefore, with luck, will increase the |
96 |
> number of folks reading it. With the installer getting better, it's not |
97 |
> like newbies necessarily /have/ to read it any more, to get a working |
98 |
> install, but I believe we'll all be happier if people continue to read |
99 |
> the docs anyway, and it follows that making that easier to do is a goal |
100 |
> worth pursuing. Hopefully, this proposal, or anyway the discussion that |
101 |
> might follow telling me why it's not as great as I think it is (;.;) |
102 |
> before getting any feedback, will advance that goal. |
103 |
> |
104 |
> Either way, if I may be of help... =8^) |
105 |
> |
106 |
|
107 |
The only thing Daniel has revealed in his brief review is that *he* is |
108 |
too advanced for the long-format handbooks. All he needs is the quicker |
109 |
checklist form of the handbooks (the existing quick install guides) |
110 |
since he has the process more or less memorized. I've spoken with Daniel |
111 |
about this a few times now on both his blog and on IRC. The GDP |
112 |
disagrees with what he thinks needs to be done. |
113 |
|
114 |
A new user, both new to installing Gentoo and new to Linux, needs the |
115 |
longer format handbooks that we have now. The reason why those go into |
116 |
their detail is that users *will need to know* some basic terminology |
117 |
and linux commands. They won't know what the hell they're doing if they |
118 |
follow a one-page guide and then reboot into their system. When they run |
119 |
into trouble, they'll have no idea what phrases like "chroot the |
120 |
tarball" and other jargon mean when they ask for help in the forums and |
121 |
on IRC. |
122 |
|
123 |
Dunno what the hell you're talking about by "integration", but I will |
124 |
say this: users need the Portage handbooks and the ever-critical |
125 |
networking handbook too. They aren't going away. The handbook structure |
126 |
will stay as-is. Changing it will not help the most central problem |
127 |
we're up against: that users simply *do not read* documents, period. |
128 |
It's not in their nature. No amount of restructuring or other |
129 |
handholding will change that for them; they have to take the plunge into |
130 |
the technical world of Gentoo on their own. |
131 |
|
132 |
The only thing that might be changed is the naming convention of the |
133 |
networkless vs. networked handbooks. While messages about which one you |
134 |
should read are everywhere, somehow users still manage to miss the right |
135 |
one, either because PEBKAC or other reasons. |