You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Joshua Varner <jl...@gmail.com> on 2005/06/29 17:34:07 UTC
FAQs
I am interested in the FAQ manager position; as sad as this is, I'm
the local expert on svn since I'm the only one whose read the book yet
at our company.
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 current break down of
General Questions
How To
Trouble Shooting
Developer
Reference
reflects only one possible way of organizing the questions, and very
little granuality of concepts. Since I was thinking about volunteering
for the position I went to look at the existing FAQs, and it's hard
just to find out what is currently there.
I would recommend providing multiple ways of examining the questions
General ( About, Getting Involved, Development, References,
Comparison . . . )
How-To
By Task (Repository Administration, Commiting, Branching, Error
Recovery . . . )
By Platform (All, *nux, Windows, BSD . . . )
Known Problems/Troubleshooting
By Task (Repository Administration, Commiting, Branching, Error
Recovery . . . )
By Platform (All, *nux, Windows, BSD . . . )
By Program (moddav, svnserve, svnclient, bindings, . . . )
Switching from X (Perforce, CVS, Clearcase . . . )
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.
I would definately need help as our office runs entirely on linux and
uses svnserve, so I have tended to skip the http and windows messages,
but I do read most of the e-mail coming through.
TIA,
Josh
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: FAQs
Posted by kf...@collab.net.
Gabor Szabo <sz...@gmail.com> writes:
> > > I also think more links to the relevant discussions on the
> > > various mailings list
> > > and to the entries in the Subversion book would allow users to
> > > research a topic better.
> >
> > I agree, that's one of the things I wanted to do, I've been saving
> > e-mails that look promising.
Wow, this would be terrific -- it would be a big improvement in the
FAQ.
/me gets excited
No need to do them all at once. Sending individual patches for
specific questions is fine.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: FAQs
Posted by Gabor Szabo <sz...@gmail.com>.
back to the mailing list with my response. I guess you wanted to send
it there too.
On 6/30/05, Joshua Varner <jl...@gmail.com> wrote:
> On 6/30/05, Gabor Szabo <sz...@gmail.com> wrote:
> > On 6/29/05, Joshua Varner <jl...@gmail.com> wrote:
> > > I would recommend providing multiple ways of examining the questions
> >
> > This sounds like a good idea. In addition one might want to examine the
> > different ways people ask a question related to a topic and include all
> > those ways in the FAQ.
> >
> > I also think more links to the relevant discussions on the various mailings list
> > and to the entries in the Subversion book would allow users to
> > research a topic better.
> >
> I agree, that's one of the things I wanted to do, I've been saving
> e-mails that look promising.
>
> >
> > > The major concern with maintaining this kind of list would be
> > > automation, and it appears the the current FAQ is straight HTML,
> >
> > Have you checekd YAML to be used for source file format? AFAIK there are
> > tools in various languages to process YAML files. (see http://www.yaml.org/ )
> >
> I took a brief look a YAML and it looks like it would work. The
> question is what would be supported by Collabnet, since they are the
> ones hosting the site. I could probably do it with Javascript, too.
> But it comes down to what the hosting server is interested in
> supporting, either during the uploading process or on the fly (a la
> Javascript).
>
> The first patch I would want to do would be to provide this kind of
> organization. I can create an off-line process to generate the pages
> and send in a patch like that, but I would like to know what type of
> tool to use prior to doing that work.
AFAIK it would be better to create the HTML(s) off-line
or by the process that generates the web site from the repository.
Gabor
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: FAQs
Posted by Gabor Szabo <sz...@gmail.com>.
Hi Josh,
while I am also newby to the dev list let me address your message
On 6/29/05, Joshua Varner <jl...@gmail.com> wrote:
> I would recommend providing multiple ways of examining the questions
This sounds like a good idea. In addition one might want to examine the
different ways people ask a question related to a topic and include all
those ways in the FAQ.
I also think more links to the relevant discussions on the various mailings list
and to the entries in the Subversion book would allow users to
research a topic better.
> The major concern with maintaining this kind of list would be
> automation, and it appears the the current FAQ is straight HTML,
Have you checekd YAML to be used for source file format? AFAIK there are
tools in various languages to process YAML files. (see http://www.yaml.org/ )
Gabor
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: FAQs
Posted by kf...@collab.net.
Joshua Varner <jl...@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
Re: FAQs
Posted by Joshua Varner <jl...@gmail.com>.
On 30 Jun 2005 10:24:49 -0500, kfogel@collab.net <kf...@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:
Re: FAQs
Posted by kf...@collab.net.
Joshua Varner <jl...@gmail.com> writes:
> I am interested in the FAQ manager position; as sad as this is, I'm
> the local expert on svn since I'm the only one whose read the book yet
> at our company.
>
> 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 current break down of
> General Questions
> How To
> Trouble Shooting
> Developer
> Reference
> reflects only one possible way of organizing the questions, and very
> little granuality of concepts. Since I was thinking about volunteering
> for the position I went to look at the existing FAQs, and it's hard
> just to find out what is currently there.
>
> I would recommend providing multiple ways of examining the questions
> General ( About, Getting Involved, Development, References,
> Comparison . . . )
> How-To
> By Task (Repository Administration, Commiting, Branching, Error
> Recovery . . . )
> By Platform (All, *nux, Windows, BSD . . . )
> Known Problems/Troubleshooting
> By Task (Repository Administration, Commiting, Branching, Error
> Recovery . . . )
> By Platform (All, *nux, Windows, BSD . . . )
> By Program (moddav, svnserve, svnclient, bindings, . . . )
> Switching from X (Perforce, CVS, Clearcase . . . )
>
> 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.
>
> I would definately need help as our office runs entirely on linux and
> uses svnserve, so I have tended to skip the http and windows messages,
> but I do read most of the e-mail coming through.
As David James pointed out, patches to the FAQ are always welcome.
Here's what I just wrote to someone else about this:
| ...check out
|
| http://subversion.tigris.org/mailing-list-guidelines.html#patches
|
| for guidelines on posting patches -- these apply to faq.html patches
| as to anything else. Then, just sit on dev@ and users@ watching the
| mails go by, and when you see a question frequently asked, post a new
| faq.html patch. People here will review and apply it if appropriate,
| and after a run of good patches, we'll dispense with the overhead and
| just ask you to commit directly. (Usually there's no need to apply
| for commit access, someone will notice and propose you. See the
| HACKING file for the mechanics of how commit access is granted.)
|
| Thanks for volunteering!
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.
Are you really seeing many of these emails? On this list, or on
private internal lists? Based on what you see in those emails, do you
think that finer-grained categories in the FAQ would have made the
difference for those users?
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?
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: FAQs
Posted by David James <ja...@gmail.com>.
On 6/29/05, Joshua Varner <jl...@gmail.com> wrote:
> I am interested in the FAQ manager position
You're hired! ;) The Subversion project is always open to contributions.
Submit FAQ patches to the list as needed. We'll update the FAQ. Once
you have a few patches under your belt, you can apply for commit
access.
Good luck!
Best,
David
P.S. Looks like you've already submitted a patch to svn.el. Great!
Keep up the good work!
http://svn.haxx.se/dev/archive-2005-06/0336.shtml
--
David James -- http://www.cs.toronto.edu/~james
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org