Re: Documentation and Usability
On 2004-01-17, Mac McCaskie penned:
> Paul Morgan wrote:
>
>> On Sat, 17 Jan 2004 13:18:50 -0600, Mac McCaskie wrote:
>>
>> So you would wish, for instance, to deprive me of a package which I
>> can understand and use simply because the documentation is not
>> adequate enough for you, or for somebody non-me, anyway?
>
> Yes, because otherwise a value judgement is imposed on the potential
> users' level of competence. Wouldn't you like to have the opportunity
> to use something you just heard of? Under these qualifications, only
> those in possesion of the required knowledge would be able to use it.
Yes, I would like to use something I've just heard of. Often, if I've
just heard of it, it's pretty freakin' new, and the documentation isn't
all there. I'd still like to be able to play with it.
>
>> Heck, if I need it, I'll use what I can figure out, even if I have to
>> go to the source code to understand some of it. I think that the
>> only criterion should be that a package doesn't break the system.
>
> Then good for you being able to read the source code AND have the time
> to do it and too bad for those that can't.
I don't think anyone is saying that documentation isn't desirable. What
many of us are saying is, give us the tools first, then worry about the
documentation. You seem to be stuck in a proprietary model, where the
only person who can provide documentation is the developer, whether that
be the upstream developer or the package maintainer. This simply isn't
the case. If users who can read the source have access to the package,
then there are more *potential documenters* for the package.
> (I'll let you in on a secret, I'm raising the awareness of the need
> for documentation here.)
No, you're not. Everyone is aware that perfect documentation, or at
least present and useful documentation, is desirable. What you're doing
is irritating those people who, like me, are foolish enough to keep
reading your posts.
--
monique
Reply to: