Joshua D Doll wrote: > Saphirus Sage wrote: >> Joshua D Doll wrote: >> >>> Dale wrote: >>> >>>> Joshua D Doll wrote: >>>> >>>> >>>>> Mark Knecht wrote: >>>>> >>>>>> On Thu, Feb 5, 2009 at 12:32 PM, Paul Hartman >>>>>> <paul.hartman+gen...@gmail.com> wrote: I completely agree. I >>>>>> like the control also. >>>>>> >>>>>> I only took a *very* small exception to Joshua's statement that a >>>>>> 'new >>>>>> user' could read, follow it and understand what it's telling him/her >>>>>> to do and then do it and come out with a working machine. I think >>>>>> it's >>>>>> true if the new user builds exactly the 3 partition example shown in >>>>>> the docs and does *only* the very basic install on a machine that >>>>>> doesn't have Windows, etc. However I think that the docs (not the >>>>>> software!) could be improved to handle things like dual-boot, either >>>>>> another distro or windows, etc. which personally I think 'new users' >>>>>> come up against. Issues about stuff like where to put the MBR, >>>>>> why and >>>>>> why not to do that sort of thing, requires (or is vastly >>>>>> enhanced) if >>>>>> that new user has some knowledge about hard drives, booting, etc. >>>>>> >>>>>> - Mark >>>>>> >>>>>> >>>>>> >>>>> I 100% agree that the docs can and should cover more. Maybe a >>>>> flowchart would be useful? >>>>> >>>>> --Joshua Doll >>>>> >>>>> >>>>> >>>> I wish the man pages had more examples. Give me a real world example >>>> and I can wrap my poor brain around what it should look like when I do >>>> something. >>>> >>>> Dale >>>> >>>> :-) :-) >>>> >>>> >>>> >>> Man pages are notoriously bad. The gentoo handbook and other official >>> docs are great OTOH. >>> >>> --Joshua Doll >>> >>> >> Man pages notoriously bad?! Now that's a stance I can hardly understand, >> they've always been a godsend in my experience! Just practice using a >> command a few times, look through the options and learn it in the period >> of ten minutes, and a man page has done its purpose. If this stance is >> due to your own inadequate ability to read technical documents, then do >> not apply the lacking to anything but your own capacity for >> comprehension. >> >> >> > Just cause you haven't run across an uninformative/incomplete man page > doesn't mean others haven't. Also man pages lacking valuable > information is the reason why GNU has switched to the majority of > their packages to using info! You shouldn't flame someone because your > experiences are different from their's. > > --Joshua Doll > > >
I have to say that I have had times that even after someone showed me how to use a command, the man page made no sense still. If it doesn't make sense when you know a little about using it, how can it make sense when you don't? I think examples is a good way to do that and the more the better. Dale :-) :-)