Thread: Platform-specific "FAQs" are waaaaaay outdated
The platform-specific FAQs in the doc/ area have clearly been suffering from, er, letter rot. Quoth FAQ_Linux: "This was a problem in 1.08 [...]. It is fixed in 1.09 and 6.0" Some of the material goes on for pages about problems which have quite obviously been fixed or suggests fixes which provably don't work. To me this is clearly an out of sight/out of mind problem and it needs to be fixed, like this: * Platform-specific installation problems are documented in the installation instructions. No after the fact, "sorry the real installation procedure doesn't work for FooNix". * Regression test problems are documented with the regression tests. * Information about how to set up shared memory and other resources will also find a home in the Administrator's Guide in a to be created section. * FAQ's will be destroyed, except for a select few. In particular I'm looking at this: * FAQ_AIX: The described problems are fixed and the information is essentially given in the installation instructions. * FAQ_BSDI: Information about resource limits, see plan above. * FAQ_DigitalUnix: The summary of this is "I don't know why, but it doesn't work for me either", which is no longer true AFAIK. Last update Dec 1998 -- Remove. * FAQ_FreeBSD: Same as BSDI * FAQ_HPUX: We can keep some of this, but some of the problems are no longer there. * FAQ_Irix: Wildly obsolete. Better to remove and start over than to confuse users like this. * FAQ_Linux: same * FAQ_SCO: Seems up to date. * FAQ_Solaris: This information is better integrated into the main body. FAQ_NT is probably more accurately named INSTALL_NT, and FAQ_QNX looks more like a README_QNX. All in all, there can't really be *that* many "frequently asked questions". :-) -- Peter Eisentraut Sernanders väg 10:115 peter_e@gmx.net 75262 Uppsala http://yi.org/peter-e/ Sweden
[ Charset ISO-8859-1 unsupported, converting... ] > The platform-specific FAQs in the doc/ area have clearly been suffering > from, er, letter rot. > > Quoth FAQ_Linux: > > "This was a problem in 1.08 [...]. It is fixed in 1.09 and 6.0" Yikes, that is very old. Man, who is maintaining these. > > Some of the material goes on for pages about problems which have quite > obviously been fixed or suggests fixes which provably don't work. > > To me this is clearly an out of sight/out of mind problem and it needs to > be fixed, like this: > > * Platform-specific installation problems are documented in the > installation instructions. No after the fact, "sorry the real > installation procedure doesn't work for FooNix". > > * Regression test problems are documented with the regression tests. > > * Information about how to set up shared memory and other resources will > also find a home in the Administrator's Guide in a to be created > section. > > * FAQ's will be destroyed, except for a select few. The reason these are separate files is because at one time, people running specific platforms maintained them separately. I actually had e-mail accounts for Linux and Irix FAQ's. The maintainer could e-mail a file to an account here, and the web site and cvs would be updated automatically. Of course, having separate maintainers allowed them to keep it up-to-date with no effort on our part, but when people left, they just sat there. I am not sure if we should just clean them up to remove the old stuff, or merge them into the docs. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 853-3000 + If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania 19026
Bruce Momjian writes: > Yikes, that is very old. Man, who is maintaining these. The way I see it, at some point in the past some people have sorted out and documented most or all of the problems for certain platforms in these documents. Most of the problems were subsequently fixed, but no one bothered to update the FAQs because a) They didn't know about these documents. b) The documents named a "maintainer", so others were afraid of interfering. c) The "maintainer" was no longer around. > I am not sure if we should just clean them up to remove the old stuff, > or merge them into the docs. It is my point of view that merging them into the docs is a much better way to proceed, because it fixes a), b), and c). It also makes the docs themselves better because there's no good reason for separating out some documentation just because it's different on some platforms, causing users to look elsewhere. This is especially inconvenient if you are reading the HTML version in a browser or reading the hardcopy. The existence of a separate FAQ indicates that the information in there is not official to some extent. That doesn't shed a good light on things. Unless someone objects firmly I am at least going to clean out the ones that have not been updated since 1998, and I'll make a section in the Administrator's Guide on managing shared memory and other resources based on platform. -- Peter Eisentraut Sernanders väg 10:115 peter_e@gmx.net 75262 Uppsala http://yi.org/peter-e/ Sweden
> Unless someone objects firmly I am at least going to clean out the ones
> that have not been updated since 1998, and I'll make a section in the
> Administrator's Guide on managing shared memory and other resources based
> on platform.
Just in case you are looking for a consensus, I agree on all points...
- Thomas