The custom components in your web project should have clear and unambiguous
parameters that can be configured by administrators without the developer's
help.
Assume among other 30 components you have created for your website there is
one to show a list of registered members: "myproject:members.list". What
parameters would this component have? This depends, of course, on the nature of
the website and usage scenarios. The most common settings an administrator would
expect from a component of this intent are:
- Members per page (to set the number of members currently visible on a
webpage);
- Short / long name (to set the person name format; two radio buttons or a
drop-down list);
- Maximum description length (to set the maximum number of characters visible);
- Show e-mail address (checkbox);
- Sort list by (to set the sort column);
- some other component specific parameters.
However, it is most likely that an administrator (expecting him or her being
a programmer is a common mistake) will get confused seeing parameters like:
- Caching strategy;
- JSON request format;
- Authorized user groups (meaning to select the user groups that are allowed
to view the component output).
If you think such parameters are still required for some reason, isolate them
into a group (by the name of "Advanced settings" or something like
that) and describe in the website specifications.
- Review the settings sheet of each of the custom components in your
website's public section. Make sure each of the parameters and options has a
clear title and is well documented. The parameter names should give an
administrator a quick understanding of the parameter meaning and possible
values. It is wise to check each of the parameters to ensure they behave as
expected.