Le 17 mars 2004, =E0 4:18, Alexander Hansen a =E9crit :
> Let me express my violent agreement with Daniel here.
>
> I, personally, have been very receptive to people who provide specific=20=
> examples where they find the documentation confusing. That being=20
> said, it doesn't happen very often.
You're one of the few, together with Martin Costabel, from my=20
experience and I thank you both very much for this.
> Perhaps someone (such as myself) should send out a call on=20
> Fink-beginners?
> On Mar 16, 2004, at 8:16 PM, Daniel Macks wrote:
>
>> On Wed, Mar 17, 2004 at 12:41:20AM +0100, David H. wrote:
>>>
>>> Please read this. This is from a private conversation I think it is
>>> valuable input.
>>
>> I've hesitated about sending this response for fear that it's going =
to
>> sound quite rude or flame-ish, and that's certainly not the way I
>> intend it (esp. towards the struggling user). I'd love to have our
>> docs be clearer (for everyone) and more newbie-friendly, but...
No, critiscim is always the way to improve, why should we take this the=20=
bad way?
>>
>> We (now) know that "some of our instructions" about "some stuff" are
>> lacking "some information" and/or aim too high because some users =
only
>> have "a certain level of knowledge". That seems like some rather not-
>> very-constructive criticism. Sure, we'd love to improve the docs, but
>> *how*? We can write all day but until someone says "this spot is
>> unclear" or "I misread this part to mean ..." or "it took me a while
>> to realize I had to ..." or "what the hell is a 'source tarball'?",
>> we're just so many more blind jigsaw-puzzlers.
The problem is maybe not to tell the user who asks what seems a very=20
basic question, "don't use this if you don't understand what it does",=20=
or "read the manual" even before attempting to give him the mere=20
beginning of an answer. If the user asks, assume that it is because=20
something is unclear, otherwise why would he ask? The problem is to=20
find exactly what is unclear and if the user does not know the matter,=20=
it's very difficult, not to say impossible, for him to express it in=20
terms you expect.
>> What areas in particular need clarification, more background, more
>> examples, definitions of terms, different organization, or links to
>> general Mac or Unix or somewhere-else sites?
Every part after installation for me, but I cannot judge for others,=20
needs clarification, examples (maybe that is where the documentation is=20=
lacking the most), a glossary would not hurt too. I've already proposed=20=
to install a search engine on the doc, so that the user would not waste=20=
a day searching something he finally does not find, simply because the=20=
way he asks is not the way the doc is structured.
For example, documentation is not always included in a software, and=20
when the user miraculously finds the site (nowhere is explained you=20
should always type fink info foo to merely access the web site for foo,=20=
well it is explained but completely hidden or presented as something=20
incident, which it is not), he has instructions for other systems,=20
which most of the time don't apply to Mac OS X. So a part about=20
customizing package, something general which could help the user to=20
enter this world, with explanation specific to Mac OS X:
what to do after installation:
1 - fink info for to find the site and read more info about the package
2 - man foo for explanation about the options for foo
3 - some examples of customization in particular for the most used=20
packages, or for those which customization is very specific to Mac OS X
4 - some links to other sites specialized in an array: how to customize=20=
the shell, how to change colors, how to enable sound, etc...
In fact, it could be two parts, one very general, about Unix, one more=20=
specialized about customization.
>> Are we assuming too much
>> unix knowledge for Mac people who are used to point'n'click and were
>> told to "use Fink to install Program X" but aren't aware they have to
>> open a Terminal and type 'program-x' or that 'man foo' will usually
>> tell them about program foo or how the filesystem is organized?
Yes, exactly. Assume the user does not even know what a terminal is,=20
what a man page is, etc... If the user knows, he just skip the section,=20=
if the user does not know, it will be taught, and that way, he can go=20
on.
>> Are we
>> assuming too much Mac knowledge for users who are coming from a Unix
>> or Windows world?
Yes, exactly. You can say it just by reading the questions on=20
fink-beginners or fink-users. Those users assume the system they have=20
will behave exactly as they were used to. That's not always the case.=20
So here, again, a section about differences would not hurt.
>> Are we assuming too much computer knowledge in
>> general for people who are used to having everything set up by their
>> 12-year-old son and suddenly are faced with unfamiliar terms and =
ideas
>> ("compile", "install", "package")?
It may be too. Here the glossary could be a very useful help. As we=20
translate the doc, it's relatively easy to collect specific words,=20
which could be the beginning of the glossary. Kind of dictionary of=20
computing.
>> Is there so much documentation on
>> some things that users can't find a particular item because it's
>> difficult to navigate or not organized well, and then users give up
>> and say "the thing I need is not documented"?
Yes, this is true too. I would not say too much documentation, but it=20
is not organized the way an average user will search it. In general,=20
from my experience, you should know where to search to find the answer.=20=
Particularly true for everything under doc: contents, when it exists,=20
is only developed by chapter, but generally the user searches for=20
something specific, so why not include the sections/subsections in=20
contents. It may help to find something.
And again a whole doc on using packages could be very beneficial.
Then something more basic about porting, packaging, etc... The way it=20
is organized now assumes that the user is a skilled programmer, which=20
is not always the case. Again, basics are missing here. And it's very=20
difficult to find sites about porting on the Unix side of Mac OS X. I=20
think for example on the section about libraries, after reading it 10=20
times at least, it's not so clear to me. Accustomed to software which=20
does the job for me, I don't even know how to do it manually (same case=20=
for most PC programmers).
>> Are the docs too
>> comprehensive with no overview or other concept-level entry-pount
>> (vs. knowing what one is looking for and either where to find info
>> about that topic or what keyword to use to search for it)?
Exactly.
It's a huge task, but it can be better done step by step, day after=20
day, improving slowly. Just collecting questions on #fink,=20
fink-beginners, fink-users, fink-developers, should give the basis for=20=
improvement.
That's the opinion of someone who did not know anything of Unix two=20
years ago, anything of Mac programming three years ago, anything of gtk=20=
one year ago, etc... but is a Mac user since 30 years and used 2/3/4=20
generation languages on PC just for ease her job for about the same=20
time.
Mich=E8le
<http://micmacfr.homeunix.org>
|
