Is your component's config help up-to-date?

[Michael D. Crawford]

I'd like to request that if you are responsible for an option that can be
configured in the kernel, that you look at the help for it and make sure it is
currently up to date.

I know that it is more important to the correct function of the kernel that your
software actually be fully implemented and bug-free, but the config help is
often the only thing that a lot of people will know about your part of the
kernel until they've been working with the new system for a while.  At the very
least you'll save yourself answering some questions and looking into bogus bug
reports if you make sure the help is correct.

It's my experience that after a while of testing lots of new kernels I stop
looking at the help much.  Maybe you haven't looked at it very much since you
originally composed it, but the behaviour of your component has changed so that
it no longer matches the description.

This is in the file linux/Documentation/Configure.help (to edit it).  You can of
course also read it by configuring a kernel and checking the help on your
option.

- Are there any questions frequently asked on the mailing list that you could
head off by
  answering them in the config help?

- Is the help written in a clear and unambiguous way?  Have a friend who isn't
an expert 
  read it and tell you what he thinks it means.  Rememember that many people who
will be 
  reading it do not have English as their mother tongue and may even be using a
translation
  dictionary to understand it.

- Does the help describe the current behavior of your option?

- Have you added support for new hardware in a driver that's not yet mentioned
in the help?

- If the behavior depends on the configuration of other options, is the
described behavior
  actually what currently happens when those other options are set various
ways?  I know this
  can take sime time to test out the different options by actually building and
trying out
  the kernels but it's important to head off a bunch of mystified users.

- Does the recommendation that the help gives correspond to your current
thinking?

- Are any URL's or references to external doc given in the help correct?

- Could you add any URL's or references to doc like HOWTOs that would be
helpful?

Yours,

Mike
-- 
Michael D. Crawford
GoingWare Inc. - Expert Software Development and Consulting
http://www.goingware.com/
[e-mail]

   Tilting at Windmills for a Better Tomorrow.