Dale wrote:
> 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
>
> :-) :-)
>
>
I'd wager that examples are the responsibility of third parties.
Frankly, if I've read a man page and found it inadequate, a quick google
search usually will come back with enough examples to resolve any
problem. I'm not saying a manpage should be without any examples at all,
but if the provided documentation isn't thorough enough, that's what
these mailing lists and forums are for.
