On Wed, 2003-08-13 at 20:05, Paul L. Allen wrote: > Ron Guerin writes: > > > I don't think spending an evening wandering around Google and hitting > > dead links is a substitute for proper documentation. > > I would agree there - googling is very much a last resort. And the > whole point of open source is that we all put back in whatever way we > can, so a collaberative documentation effort can pay dividends very > quickly.
Obviously, I agree! > I'd also say that "search the archives" is no substitute for a proper > FAQ. I remember the days when newsgroups and mailing lists DID have > FAQs. Then search engines came along and everybody saw them as a > substitute for an FAQ. And for a few months people were correct. For > a few months a google search would be just as quick and effective as > a real FAQ. But after a couple of years, a google search is a complete > pain. HUNDREDS of results pages with people asking the question you > want answered and the response is invariably "do a google search of > the archive." The original answer to that question is ZILLIONS of > pages down the list and unless you have a few months to waste you'll > never find it. I remember back around that time there was also the popular belief that things committed to the Web were preserved for the ages. I'll refer back to a specific piece of qmail documentation I'd been looking for... I found plenty of references to the document in the first 10 results. The problem is the actual document itself has nearly fallen off the face of the earth. I say nearly, because I _did_ find it. In the WayBack machine, which truly is the last station before oblivion. > "Search the archives" equates to "nobody can be bothered to maintain > an FAQ because nobody has realized just how useless a google search is > when dealing with a large archive where most questions are answered with > 'search the archives.'" The qmail list is one of the worst I've seen > for this. Yes, if you have a lot of time to spare you can eventually > find the answer. But "search the archive" is never going to be as > quick a solution as "the answer is in the FAQ." There will probably always be gems in the archives that appear nowhere else. But "search the archives" should only be the answer for very recent, or very obscure things that have yet to find their way into the documentation. Archives should supplement documentation, not _be_ documentation. > My apologies if I've offended anyone, but it's late, I've had a lot of > wine, and I've wanted to get that one off my chest for well over three > years. I even put my money where my mouth is. If there is an FAQ (on > whatever) and I have something useful I submit it to the maintainer. But > all too often the FAQ has been abandoned in favour of "search the archive." I don't think anyone's going to be offended. The fact that we don't have more documentation is our responsibility and no one else's. In an Open and Free project like this, particularly one with so many users, the developers shouldn't be producing the admin and user documentation. I consider that a waste of their valuable time, when they can be writing more code, doing more code analysis, ripping more code _out_, stuff that developers do. The exception there would be that obviously, some non-trivial amount of developer participation would be required for documenting the vpopmail API. Speaking for myself, I can't put a line of C code together, but I can string some words together into a sentence. That should be true of many others here, and together, we have the potential for translations (most important for the FAQ) into many languages. It could be only a few of us will work on it sporadically. And that's ok too. The important thing is to get started on it. I was going to fix some things for myself, and now I'm going to submit those fixes for everyone else's benefit. It's how much of the code gets written in Free and Open software. Someone who can, scratches an itch and makes it available to everyone else. Good to have you on-board! - Ron
