Mailing List Archive

how best to answer questions (was: RE: ringbuf1.nuv)
At 11:51 AM 3/24/2003 -0500, Joseph A. Caputo wrote:
[...]

>I realize we all have different personal threshholds regarding how 'basic' a
>question can be before we fire off a standard 'RTFM' response, but I
>personally wouldn't want anyone to give up on Myth or Linux in general
>because they felt the community was not supportive towards newbies. I
>thought the whole point of having a separate 'mythtv-users' list was to
>provide a forum that was more tolerant of basic setup questions.

You raise a good basic question here, Joe, but I think you also attack a
straw man.

Providing someone with a link to a specific, applicable section of a HowTo,
as Robert did, is not "a standard 'RTFM' response". When I first arrived
here, I posted a question that got a similar response (I don't recall from
whom, though Robert is surely a likely candidate), and it was to the point
and helpful. Since the information was located in an unlikely place in the
HowTo, directing me to it gave me the opportunity to suggest that it be
relocated (or referenced) in the place I *had* checked, the section that
appeared from its name to be the relevant one (instead of its actual
location in a "Miscellaneous Problems" appendix, or something like that).
Referencing existing sections of a HowTo saves the writer time, encourages
use of the HowTo by everyone here, and offers a way to promote steady
improvement of the HowTo.

For a beginner to get a direct answer here to a question that is answered
in the HowTo, someone who knows the answer needs to be willing to take the
time to compose a reply with the details, ideally a reply that is as
accurate and clear as the HowTo itself. You did offer a reply in this case,
but only in response to an earlier reply you did not care for. Perhaps this
was just timing ... you did not see the original message until after Robert
had posted his reply. Or perhaps you, like me and everyone else here, saw
the message and decided to let someone else take care of it, posting only
when you decided you didn't like the answer the "someone else " actually
gave. In either case, I'd urge you to support your view by actually writing
the sorts of reply you would like to see, so that people who prefer not to
write one-by-one answers to recurring questions can refrain from replying
but draw on these list answers to improve the HowTo and other documentation
(or, in the case at hand, fix what I too see as a design flaw).

To my eye, this list is extremely "tolerant" of "basic setup questions". No
one castigated the user for posting his question ... most of us ignored it,
and you and Robert answered it in different fashions. A considerably
touchier example is Jay's thread from yesterday, where he got responses he
found unhelpful, and responded insultingly (both to the person who had
posted the brief response -AND- to the person who had taken the time to
post a more extensive, in-line set of comments and responses to his
original post).

Even here, I felt that the original poster got about what he deserved ...
being rude to people from whom you seek free tech support for free software
just isn't smart, even if you do not understand a particular reply. I even
started to write a more extensive reply explaining to Jay what he was
missing, but as the thread continued while I was writing, he got annoying
enough that I discarded the reply unposted. I notice that no one else
stepped in to help him out either, perhaps indicating the limits on what we
as a group (including you, presumably, since you didn't step in either)
will tolerate from beginners asking questions.

In closing ... as MythTV moves from an app suited only for tinkerers to one
ready for a mass audience, a lot of things have to improve. Documentation
is one of them. That it is not currently good enough to handle all
questions by beginners (even beginners to Unix/Linux) is unfortunate but
not surprising ... free development takes you only so far, and up to now
I'd say both the app and its docs have developed pretty well. And, just to
be very clear, I think Robert is quite right to reference his HowTo when
answering questrions, leaving it to others to write immediate replies if we
are willing to make the effort (since he's already *made* his effort by
writing and maintaining the HowTo in the first place).
RE: how best to answer questions (was: RE: ringbuf1.nuv) [ In reply to ]
>
>
>Anyway, it seems to me that a project like MythTV attracts a higher
>percentage of Linux newbies than many others, because... well, because it's
>so cool! And, even though the documentation is pretty good & a lot of good
>effort has been expended on it, sometimes no amount of documentation is
>enough for a complete newbie (not necessarily kmallick2000) who is not
>familiar with fundamental *nix concepts, like paths & command line syntax.
>For instance, the documentation you pointed to shows an example for what to
>do if you want to change the default '/mnt/store' to '/var/video'. It would
>be easy for a real newbie to assume that if they don't want to change the
>default that they don't have to do anything, as there is no example for
>creating & setting the permissions on the '/mnt/store' directory.
>
I agree on this specific issue. Perhaps the docs should say something
like "most systems by default do not have a /mnt/store directory, you
must either create it or change the path to a directory that does exist".

However, in general I don't think it is rude to just point someone to
the manual. It might be a bit terse just to say "read the docs" but
supplying a link not only to the docs, but to the specific section that
will help the newbie shows that some consideration was put into the
question. Sure its short and direct, but the documentation is likely to
be more complete and correct than anything you could whip off in 15
seconds. For instance (not trying to pick on you) half of your two part
reply was wrong! /mnt/store and /mnt/store/ seem to be equivalent. So in
effect you have just made the newbies life more complicated by
introducing a red herring. Also as Jay showed yesterday, sometimes the
"two line reply" that you suggest seems to inexplicably infuriate the
newbie. What most people on the list would interpret as "brief but
helpful" or perhaps even "terse but to the point" was taken by him to be
an insult of some kind. This is especially strange since Edward's reply
was pretty long, polite and helpful. My point is that pointing to a
specific section of the documentation might be more helpful than any two
line reply and could avoid being seen as rudely terse.



cedar
RE: how best to answer questions (was: RE: ringbuf1.nuv) [ In reply to ]
> -----Original Message-----
> From: mythtv-users-bounces@snowman.net
> [mailto:mythtv-users-bounces@snowman.net]On Behalf Of Cedar McKay
> Sent: Monday, March 24, 2003 1:05 PM
> To: Discussion about mythtv
> Subject: RE: how best to answer questions (was: RE: [mythtv-users]
> ringbuf1.nuv)
>
>
> Sure its short and direct, but the documentation is likely to
> be more complete and correct than anything you could whip off in 15
> seconds.

Except in this case, we seem to have located a potentially unclear or
confusing portion of the docs (i.e., the omission of specifics about
creating the '/mnt/store' directory). Don't get me wrong; I think the docs
are great, but just like the source code are constantly being refined. So
here's a refinement to be made. In this case, I saw that the docs don't
actually say to create '/mnt/store', so I thought I more specific reply was
in order. Of course, I guess I do tend to give most people the benefit of
the doubt & assume that they have read & followed (or at least think they
have) the manual. Maybe that's not a good thing to assume, but then I'm a
'glass-is-half-full' kind of guy :-)

> For instance (not trying to pick on you) half of your two part
> reply was wrong! /mnt/store and /mnt/store/ seem to be equivalent. So in
> effect you have just made the newbies life more complicated by
> introducing a red herring.

I still maintain that I've seen this be an issue somewhere! :-) In
retrospect, I think it was on HP/UX and had to do with a chain of symbolic
links that crossed and re-crossed various NFS mount points... sheesh, what a
mess that was...

> My point is that pointing to a
> specific section of the documentation might be more helpful than any two
> line reply and could avoid being seen as rudely terse.
>

I don't disagree, I just felt that if a helpful, personal response was
convenient (at the discretion of the responder), that it would be a good
thing *in addition to* a reference to the appropriate docs.

All that being said, it's been a long time since I really looked at the
howto, and I didn't make the connection that Robert is the maintainer (kudos
to you, Robert!) If I were in Robert's position, I probably would have done
responded similarly. I can't tell you how many times I've written in-house
tools with complete documentation (generously provided both electronically &
hard copy!), only to have co-workers ask the most basic of questions. It
tends to get me quite annoyed, since I went to great effort to provide
usable documentation. And you're right, Robert's reponse was terse, but not
rude. There have been many times when I wished I could tell my co-workers
to RTFM, but it's much harder to do that without looking like a jerk when
the person is standing in front of your desk. So I guess I've just been
conditioned to provide a little hand-holding. Maybe if I institued an
email-only support policy...


Anyway, I don't mean to offend anyone or insinuate that anyone has been
rude. If anything, it's a good measure of the maturity of the project that
many questions *can* be answered by pointing to the docs. And, if not,
someone will almost always offer a more detailed solution.

-Joe C.
RE: how best to answer questions (was: RE: ringbuf1.nuv) [ In reply to ]
I've just followed the thread on answering newbie questions, and as a
relative newbie (of about 2 weeks) I thought I'd add some comments.

1) The docs are great, but they could be organised a little better

2) I think the project would really benefit from a FAQ-O-Matic type site.
There are masses of different hardware, distro, config, and library
combinations being used out there. If there was some way of contributing
information about these then I think we could all benefit

3) We really seem to lack a 'what if it goes wrong document'

All of the above are not criticisms, they're just helpful suggestions, and I
am prepared to help out myself in assisting document owners redraft sections
of the docs if that would be helpful.

Malcolm
RE: how best to answer questions (was: RE: ringbuf1.nuv) [ In reply to ]
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Please send your suggestion on how you feel the HOWTO could be better
organized to the address I have listed in the document.

Thanks.

-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 7.0.3 for non-commercial use <http://www.pgp.com>

iQA/AwUBPn9niPc1NpCTlP0JEQJqDQCfQ+3DtJLV6lQgMtrQ4qaEUaorOBIAoNL/
v5rAt+cUXJa3eg2uy7a8CRj2
=kHme
-----END PGP SIGNATURE-----
RE: how best to answer questions (was: RE: ringbuf1.nuv) [ In reply to ]
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

> Except in this case, we seem to have located a potentially unclear
> or confusing portion of the docs (i.e., the omission of specifics
> about creating the '/mnt/store' directory).

Uploaded to CVS.

-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 7.0.3 for non-commercial use <http://www.pgp.com>

iQA/AwUBPn9oRfc1NpCTlP0JEQJ4+gCcC/GwVZvyki/Rpot4dyW/QqTZqsgAn2uB
XnLn9GSR6+W7gBI+UCAZD+Ov
=rSNe
-----END PGP SIGNATURE-----