Re: why wast time to write a FAQ?
A manual does not provide the same service that an FAQ provides. The primary difference is the organization of the information. An FAQ is organized as a list of questions and answers so that readers can find the question that they are interested in. A reference manual is organized by feature or functionality so that readers can find the feature they want to learn more about. A user guide is organized by process (or use) so that readers can find out how the software applies to the way they do their "work". The above assumes that the information is the same. That may be the case but in practical terms since the focus of each is different, the information included isn't the same. For example, the FAQ would probably give a simple or direct answer to the question and reference "the CVS manual" for the complete answer or related topics. To assume that one form of documentation will serve all types of readers and their diverse needs is shortsighted. To assume that one form is always more important than the other forms is also shortsighted. To assume that someone would update one form while leaving the other alone is yet again demonstrating lack of foresight. (For the dim-witted, of course you update the CVS manual if you find something that isn't documented correctly. But no matter how complete the CVS manual is, it will not eliminate FAQ's because it isn't organized in a QA structure.) By the way, please forget that I mentioned anything about maintaining an FAQ. It's obvious that it wouldn't improve anything nor keep "old-timers" from flaming newbies. Goodbye, Craig - Original Message - From: Greg A. Woods [EMAIL PROTECTED] To: Craig Saunders [EMAIL PROTECTED] Cc: [EMAIL PROTECTED]; Craig R. Saunders [EMAIL PROTECTED] Sent: Friday, September 15, 2000 1:13 AM Subject: why wast time to write a FAQ? [ On Thursday, September 14, 2000 at 17:55:20 (-0700), Craig Saunders wrote: ] Subject: Re: What is Cederqvist? If Greg thinks it would be a good idea and he (and others) would be willing to forward their answers of FAQ's, I would be willing to edit and compile the FAQ list, post it regularly and keep it on a publicly accessible web site. (I would also scan the mailing list for potential FAQ's and proactively update the FAQ list. And, with a little reluctance, reconcile when old-timers have different opinions on how to answer a question.) I would much much sooner see someone, anyone, take note of questions that frequently appear in this (and any other related) forum and to (re)write the manual sections that have thus far been inadequate in providing the information sought by those asking the questions Hopefully that person would be given have commit access to at least the documentation sub-directory of the shared repository once they've provided one or two such fixes to the manual. I'd suggest that this person take the time to query (offline) people who ask FAQs to find out directly why they didn't find the answer they were looking for in the manual. That way they can find out whether or not the person even looked in the manual in the first place. IIRC it was Per Cederqvist who first decided that a FAQ was a bad form of information presentation in this context and though I originally was wary of losing the then gargantuan FAQ, I've since not missed it one little bit. There were at least several people far more worried about the disappearance of the FAQ at the time, but it's editor agreed with Per and given the massive effort that would have been required to continue to maintain the full FAQ nobody was willing to step up and take it on. Perhaps if the person editing the FAQ were also dedicated to updating the manual and keeping it relevant to user needs then I wouldn't argue against a general FAQ. However with very limited volunteer resources I'm quite certain that maintenance of an FAQ should be the lowest possible priority in the project. BTW, this is a generic issue that applies to any software package which has an active user forum such as info-cvs is. -- Greg A. Woods +1 416 218-0098 VE3TCP [EMAIL PROTECTED] robohack!woods Planix, Inc. [EMAIL PROTECTED]; Secrets of the Weird [EMAIL PROTECTED]
Re: why wast time to write a FAQ?
A manual does not provide the same service that an FAQ provides. The primary difference is the organization of the information. An FAQ is organized as a list of questions and answers so that readers can find the question that they are interested in. A reference manual is organized by feature or functionality so that readers can find the feature they want to learn more about. A user guide is organized by process (or use) so that readers can find out how the software applies to the way they do their "work". The above assumes that the information is the same. That may be the case but in practical terms since the focus of each is different, the information included isn't the same. For example, the FAQ would probably give a simple or direct answer to the question and reference "the CVS manual" for the complete answer or related topics. To assume that one form of documentation will serve all types of readers and their diverse needs is shortsighted. To assume that one form is always more important than the other forms is also shortsighted. To assume that someone would update one form while leaving the other alone is yet again demonstrating lack of foresight. (For the dim-witted, of course you update the CVS manual if you find something that isn't documented correctly. But no matter how complete the CVS manual is, it will not eliminate FAQ's because it isn't organized in a QA structure.) By the way, please forget that I mentioned anything about maintaining an FAQ. It's obvious that it wouldn't improve anything nor keep "old-timers" from flaming newbies. Goodbye, Craig - Original Message - From: Greg A. Woods [EMAIL PROTECTED] To: Craig Saunders [EMAIL PROTECTED] Cc: [EMAIL PROTECTED]; Craig R. Saunders [EMAIL PROTECTED] Sent: Friday, September 15, 2000 1:13 AM Subject: why wast time to write a FAQ? [ On Thursday, September 14, 2000 at 17:55:20 (-0700), Craig Saunders wrote: ] Subject: Re: What is Cederqvist? If Greg thinks it would be a good idea and he (and others) would be willing to forward their answers of FAQ's, I would be willing to edit and compile the FAQ list, post it regularly and keep it on a publicly accessible web site. (I would also scan the mailing list for potential FAQ's and proactively update the FAQ list. And, with a little reluctance, reconcile when old-timers have different opinions on how to answer a question.) I would much much sooner see someone, anyone, take note of questions that frequently appear in this (and any other related) forum and to (re)write the manual sections that have thus far been inadequate in providing the information sought by those asking the questions Hopefully that person would be given have commit access to at least the documentation sub-directory of the shared repository once they've provided one or two such fixes to the manual. I'd suggest that this person take the time to query (offline) people who ask FAQs to find out directly why they didn't find the answer they were looking for in the manual. That way they can find out whether or not the person even looked in the manual in the first place. IIRC it was Per Cederqvist who first decided that a FAQ was a bad form of information presentation in this context and though I originally was wary of losing the then gargantuan FAQ, I've since not missed it one little bit. There were at least several people far more worried about the disappearance of the FAQ at the time, but it's editor agreed with Per and given the massive effort that would have been required to continue to maintain the full FAQ nobody was willing to step up and take it on. Perhaps if the person editing the FAQ were also dedicated to updating the manual and keeping it relevant to user needs then I wouldn't argue against a general FAQ. However with very limited volunteer resources I'm quite certain that maintenance of an FAQ should be the lowest possible priority in the project. BTW, this is a generic issue that applies to any software package which has an active user forum such as info-cvs is. -- Greg A. Woods +1 416 218-0098 VE3TCP [EMAIL PROTECTED] robohack!woods Planix, Inc. [EMAIL PROTECTED]; Secrets of the Weird [EMAIL PROTECTED]
Re: why wast time to write a FAQ?
Greg, BTW, I did write an FAQ for my own purposes. Based on my discussions with you, it was clear that it would serve little purpose posting it to the mailing list other than to give you more reasons to bash someone. You obviously follow your own advice. You don't think about how your postings to the mailing list affect others or affect the product. I know you want to promote CVS but the way you do it holds it (and you) back. It is so important to you that your opinion is the one and only opinion that the mailing list holds. You could have said "I prefer to use the CVS manual. Therefore, I don't see the need of an FAQ. But others may think differently than I do so they may find an FAQ useful. So go ahead. Just make sure anything you add is also covererd in the CVS manual." That would have been inclusive and the community would have been that much better. And you might have learned something in the process. Oh well. Too bad. Good luck Maybe you'll learn some day. Craig - Original Message ----- From: Craig Saunders [EMAIL PROTECTED] To: Greg A. Woods [EMAIL PROTECTED] Cc: [EMAIL PROTECTED]; Craig R. Saunders [EMAIL PROTECTED] Sent: Friday, September 15, 2000 10:21 AM Subject: Re: why wast time to write a FAQ? A manual does not provide the same service that an FAQ provides. The primary difference is the organization of the information. An FAQ is organized as a list of questions and answers so that readers can find the question that they are interested in. A reference manual is organized by feature or functionality so that readers can find the feature they want to learn more about. A user guide is organized by process (or use) so that readers can find out how the software applies to the way they do their "work". The above assumes that the information is the same. That may be the case but in practical terms since the focus of each is different, the information included isn't the same. For example, the FAQ would probably give a simple or direct answer to the question and reference "the CVS manual" for the complete answer or related topics. To assume that one form of documentation will serve all types of readers and their diverse needs is shortsighted. To assume that one form is always more important than the other forms is also shortsighted. To assume that someone would update one form while leaving the other alone is yet again demonstrating lack of foresight. (For the dim-witted, of course you update the CVS manual if you find something that isn't documented correctly. But no matter how complete the CVS manual is, it will not eliminate FAQ's because it isn't organized in a QA structure.) By the way, please forget that I mentioned anything about maintaining an FAQ. It's obvious that it wouldn't improve anything nor keep "old-timers" from flaming newbies. Goodbye, Craig - Original Message - From: Greg A. Woods [EMAIL PROTECTED] To: Craig Saunders [EMAIL PROTECTED] Cc: [EMAIL PROTECTED]; Craig R. Saunders [EMAIL PROTECTED] Sent: Friday, September 15, 2000 1:13 AM Subject: why wast time to write a FAQ? [ On Thursday, September 14, 2000 at 17:55:20 (-0700), Craig Saunders wrote: ] Subject: Re: What is Cederqvist? If Greg thinks it would be a good idea and he (and others) would be willing to forward their answers of FAQ's, I would be willing to edit and compile the FAQ list, post it regularly and keep it on a publicly accessible web site. (I would also scan the mailing list for potential FAQ's and proactively update the FAQ list. And, with a little reluctance, reconcile when old-timers have different opinions on how to answer a question.) I would much much sooner see someone, anyone, take note of questions that frequently appear in this (and any other related) forum and to (re)write the manual sections that have thus far been inadequate in providing the information sought by those asking the questions Hopefully that person would be given have commit access to at least the documentation sub-directory of the shared repository once they've provided one or two such fixes to the manual. I'd suggest that this person take the time to query (offline) people who ask FAQs to find out directly why they didn't find the answer they were looking for in the manual. That way they can find out whether or not the person even looked in the manual in the first place. IIRC it was Per Cederqvist who first decided that a FAQ was a bad form of information presentation in this context and though I originally was wary of losing the then gargantuan FAQ, I've since not missed it one little bit. There were at least several people far more worried about the disappearance of the FAQ at the time, but it's editor agreed with Per and given the massive effort that would have been required to continue to maintain the full FAQ nobody was willing
Re: What is Cederqvist?
From: Jerry Nairn [EMAIL PROTECTED] I agree with most of your comments, but there is a FAQ at: http://www.loria.fr/cgi-bin/molli/fom.cgi Cheers, Jerry Which is not updated with QA from the list nor posted to the mailing list periodically. Also, with a personal bias, I find it difficult to navigate the FAQ-O-MATIC. At one time, I suggested an FAQ built with questions answered on the mailing list. It would reference resources such as the Cederqvist and others. It would be kept on some web site such as the FAQ-O-MATIC so that folks could get it whenever they needed it. It would be posted periodically to the mailing list so that newbies other lurkers would see it go by, hopefully before the asked their own. If Greg thinks it would be a good idea and he (and others) would be willing to forward their answers of FAQ's, I would be willing to edit and compile the FAQ list, post it regularly and keep it on a publicly accessible web site. (I would also scan the mailing list for potential FAQ's and proactively update the FAQ list. And, with a little reluctance, reconcile when old-timers have different opinions on how to answer a question.) That is what I proposed before. That offer is still open. Craig
Re: What is Cederqvist?
I find this all very amusing because when I suggested that we should have an FAQ (which would include answers to questions like this) I was told by the loud, obnoxious old-timers that we don't need an FAQ - All the answers are in The Cederqvist. But what if you don't know what The Cederqvist is? :*) My conclusion is that the old-timers want to have their obscure lingo so that they can feel superior. They can then separate themselves from the masses while at the same time, still feel good by professing to want to help the down-trodden with open-source projects. Uggh. It's also a way they can use to differentiate who to flame. Craig Saunders - Original Message - From: David Trudgett [EMAIL PROTECTED] To: [EMAIL PROTECTED] Sent: Tuesday, September 12, 2000 2:36 PM Subject: Re: What is Cederqvist? At 2000-09-12 14:24 -0400, Eric Siegerman [EMAIL PROTECTED] wrote: Indeed, I'm glad to have someone finally confirm my theory that "The Cederqvist" and cvs.info are one and the same -- and I've been using CVS since version 1.2 or 1.3. Technical terminology is one thing; jargon for its own sake risks the charge of willful obscurantism. On the other hand, I'm a total newbie to CVS, but one of the first things I found out was what the "Cederqvist" was. Of course, that doesn't mean to say that it should be referred to as the "Cederqvist" in official documentation (without explanation, at least). In casual conversation, I see no harm in calling it the "Cederqvist" (and, in fact, it has positive benefits). If someone doesn't know what it is, they can always ask, in that case. David Trudgett
