Options in specifications provide implementations the freedom to make choices about
These choices also called discretionary items, give implementers of the technology the opportunity to decide from alternatives when building their applications and tools.They describe or allow optionality of behavior, functionality, parameter values, error handling, etc. They may be considered necessary because of environmental conditions (e.g., hardware limitations or software configuration), locality differences (e.g., language or time zones), dependencies on other technologies, or the need for flexibility.
Although there are perceived benefits to providing options, there is also a downside: options increase the variations that can exist among implementations. The greatest way to undo the utility of a specification is with too many options. Basically, different implementations may specify different combinations of options. This makes comparisons between implementations difficult as well as complicates conformance testing and increases the chance of non-interoperable implementations.
Example or story from XSLT 1.0 [XSLT10] illustrating the problem? @@need example
What does it mean?Examine the reason for the option - is it to address a real, existing need? Should it really be an option or made a mandatory part of the specification? Be careful not to provide options in anticipation for something that sounds like a good idea but will probably never be realized - ask the implementers if they ever plan to need this. As the specification progresses, if the option is not implemented, consider removing it.
Why Care?
A concise list of options helps to keep the specification focused and will greatly increase the likelihood of obtaining interoperable solutions. Ensuring that only necessary opotions are contained in the specification also makes the job of the implementer easier and reduces costs.
Related:
Develop a set of tests and analyze the results to see what is implemented and how it is implemented.
Tests were used to determine if options were needed. As part of its exit criteria for Candidate Recommendation, a Working Group created a set of tests to 'test the specification'. The tests were able to show where there was need for optionality (e.g., diversity among implementations and flexibility justified) and where it was possible to narrow the choices (e.g., implementations used a much narrower set of values than what was permitted).
@@example2@@
What does it mean?Provide as much information as possible to narrow the allowable choices and to increase predictability.
For implementation dependent values or features, if possible, provide a range or set of permitted values rather than leaving it completely open.
Why Care?
Narrowing choices and increasing predictability enhance the likelihood of interoperability since the sample space for the implementer to choose from is diminished. Narrow choices and providing more information also increases the chances of correct implementations since incorrect choices are eliminated. An enumerated list of values is one way to constrain the choice of optionality.
Related:
For options, especially enumerated lists, make sure that the number of choices/options that can be implemented is known. Specifically, can zero, exactly one, or several of the allowable choices be implemented? Does this number depend on other parts of the specification or other chosen options?
Example: any specs that provide min/max values, ranges, etc.
Examples of constraints include mandating that an implementation implement only one choice, implement every choice (allowing the user to decide), be allowed to implement none of the choices, or be required to implement a specified values and as many additional values as they wish from an open-ended list.
@@example1@@
@@example2@@
What does it mean?Think about the implications of both implementing the option and of not implementing the option
Discuss the implications of either using the option or not. It may be helpful to provide rationale for choosing one option over another or for not using the option at all. Consider the unintended consequence of the option - on other options, other parts of the specification, on other specifications.
Why Care?
Thinking about implications of options forces the specification developers to seriously consider the utility of each option, which may eventually lead to the elimination of unnecessary options. Discussiong the implications of using the option or not and providing rationale as to why to choose one option over another allows implementers to make informed choices, and to understand the consequences, both intended and unintended, of their decisions.
Related:
Questions to consider include:
@@example1@@
@@example2@@
What does it mean?
Options can be useful, but non-judicious use of options increases the variability among conforming implementations. In order to minimize the unnecessary optionality, it is necessary to be able to easily identify them.
Why care?To make it easier for implementers, test creators and users to discover the choices and variability allowed. For test creators, having a name for each item and a link target for each one, allows systematic reference to individual items from test cases as well as elsewhere in the specification.
Related:
Options can be tagged in many ways. Any technique that distinguishes the optional feature from the required feature is acceptable. Some psssibilities include: putting options in a separate section; specifying options in a different font; including a unique designation to identify an option.
@@example1@@
@@example2@@