Joshua Varner <jlvarner@gmail.com> writes:
> 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.
(These are great examples, btw.)
So, this doesn't seem like a categorization issue, but rather a
failure to include the right text in the appropriate FAQ item.
> 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.
Doesn't this mean that the string "/etc" also appeared in the original
post and in the FAQ item, in addition to "import" and "original"? :-)
The wording of that FAQ item is just wrong, by the way -- a problem
against which no automation can protect us. I've fixed it in r15204.
> 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'.
Sure. I see how better browseability is a good thing, and that better
categories can help that (and would happily apply a patch for same).
I just think it can only be effective up to a point. As it would also
help us avoid duplicate items, I think it's a win all around anyway,
so I'm certainly not opposed.
> 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.
The issue here is that we can't run (on our web server) the code to
generate the FAQ from the XML master. The exact implementation and
the language used aren't a problem -- Perl, Python, whatever you want
to use. But it doesn't help much, because we can't run it where we'd
need to run it.
And versioning both the master and the generated files would be a
disaster. CVS does so for it's 'configure' script (that is, versions
it alongside the master 'configure.in') and it was a constant bug
source -- people were *always* forgetting to commit the regenerated
version when they changed the master. I don't know if this is still
going on; it was true years ago when I worked on CVS, and it taught me
that versioning generated files is a Bad Thing.
A pre-commit hook doesn't help, because usually one regenerates
several times in the course of writing new content. So even though
the pre-commit could notice that the file was regenerated at least
once, it would have no way of knowing that the file had been
regenerated after the *final* change to the master before the commit.
Technically, the pre-commit could re-do the regeneration, and then
flag an error if its result doesn't match what the user is trying to
check in. But that's getting really complex; what if, say, the
version of Perl or Python installed on the client differs slightly
from that on the server, and this affects the regenerated content in
some subtle way?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Jun 30 22:04:57 2005