On 30 Jun 2005 10:24:49 -0500, kfogel@collab.net <kfogel@collab.net> wrote:
> > I think the biggest problem right now is not the lack of FAQs you
> > have, but that they are not presented in a usable manner. I've seen a
> > number of e-mails saying 'I have this problem and looked at the FAQ,
> > but it wasn't there' that receive responses of 'Yes it it.'
> >
> > The major concern with maintaining this kind of list would be
> > automation, and it appears the the current FAQ is straight HTML, so
> > the question is what kind of build process would subversion be willing
> > to accept (offline - checking in the scripts and the generated file,
> > or on upload). I'm most comfortable with Perl or an XML/XSL type of
> > setup, but could use something else if that is desired.
> >
> Although I agree there are advantages to using an XML master file and
> generating the other formats from it, that doesn't work well with the
> way our project web site work. We can't run arbitrary scripts on the
> web server, so we'd have to keep the generated files under version
> control (yuck).
>
> Also, I must admit I'm skeptical about the claim that information is
> hard to find on there. I just go to the page and do searches, using
> my browser's search feature. This is very fast, and always gets me to
> what I need (if what I need exists at all). But when one is having a
> specific problem, and tries to find the answer by visiting the FAQ and
> navigating by category instead of just searching, I think that's
> simply a mistake. Re-categorizing the FAQ is not going to help that
> problem.
>
> I'm not opposed to breaking things down into finer categories, if only
> to make the document more browseable, and to make FAQ maintenance
> easier (by making duplicate information easier to spot). I just am
> not convinced it would help users all that much.
>
First, I apologize for going into quasi-lecture mode. The company
I work for writes Question Answering software, and consequently I
have read research related to how people find
information (i.e. Browse and Search). If there is a specific
piece of information you need then searching is a good solution,
but if that fails, or you don't have enough knowledge to know what
to search for, then browsing provides the most benefit for
you. Given that most browsers can handle the search part already
- as you were mentioning - all that is needed is browsing
support.
Second, None of the below is meant as a criticism of how a
particular problem was answered on the list, but merely an
illustration of how Browsing might have helped avoid the need to
ask on the list at all.
Example 1:
From an e-mail on June 28
http://subversion.tigris.org/servlets/ReadMsg?list=users&msgNo=34341
A user had problems after a system crash related to permissions,
and after he mentioned not finding any thing on the FAQ someone
pointed him to this entry
http://subversion.tigris.org/faq.html#reposperms in
http://subversion.tigris.org/servlets/ReadMsg?list=users&msgNo=34351
which is under the HOW-TO section with the question
"How do I set repository permissions correctly?"
But the problem is that he wasn't trying to set up the
permissions, the repository had been set up and he was having a
problem where he received an error 'Permission denied', but that
string doesn't show up in the FAQ anywhere. Same information,
different way of finding it.
Example 2:
http://subversion.tigris.org/servlets/ReadMsg?list=users&msgNo=34258
The user wanted to backup his /etc directory using svn.
which was answered with this FAQ:
http://subversion.tigris.org/faq.html#in-place-import
"How can I do an in-place 'import' (i.e. add a tree to subversion
without moving or deleting the original working copy)?"
in
http://subversion.tigris.org/servlets/ReadMsg?list=users&msgNo=34265
If you look at the original e-mail the only words mentioned in it
that are in the text of the question are import and original. His
primary thought was backing up a directory. Backup only appears
in one question about hotbackup and in the text of a question
about changing commit messages. Import appears 20 times, so that
is not necessarily helpful. Original appears only 4 times, but in
the relevant FAQ it is used only in the question and as 'original
working copy' which is not what he has. He never had a working
copy he was trying to import it. The text of the FAQ even uses
the /etc directory as the example, but the material controlled is
not the most obvious thing to look for.
Basically there is a lot of information there, but it's not
organized for people who don't have specific knowledge. That's
who the browsing will help.
> Are you really seeing many of these emails? On this list, or on
> private internal lists?
I made have overstated the number of e-mails with that exact response
but just recently there were a couple (at least one instance was a thread
that got broken by my e-mail client so I double counted that). There were
more saying such-and-such needed a FAQ, that may have blended in my
memory - let me adjust 'a number' -> 'several'.
> By the way, I don't quite see how putting the FAQ into XML would make
> the categorization problem significantly easier to solve, unless you
> were planning to generate multiple different presentations?
>
As for the XML, I have used XSLT to convert lists into HTML
before, so that what I meant there. Duplication could be
minimized by having the stlyesheet process the listings.
I'm trying to pick one that would add the least in the way of dependencies
on the project, that was more the worry. What type of dependencies does
development already have. I'll try to do something in Perl to illustrate what I
mean and send a patch.
Josh
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Jun 30 21:09:36 2005