Joshua Varner <jlvarner@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
Received on Thu Jun 30 19:36:20 2005