Good Language Practices

Good Practices

  1. Use simple direct sentences.

    Every requirement should be a single active sentence, as short as possible, but no shorter. Long rambling sentences quickly lead to confusion and error, not to mention boredom for the reader.

    Bad:
    The user must login to the system by entering a password and a username which will be verified by the system against the usernames and password that they have stored in the user information repository in order to ensure that the user is a valid user who has the right to user the solution.
    Good:
    The user will login by way of entering a valid username and password combination.

  2. Make requirements atomic.

    Requirements must be atomic in order to ensure that compliance with the requirement is measured by the single goal of the requirement being achieved. If you can think of a small number of related tests to verify a requirement’s implementation, it’s probably written at the right level of detail. If you envision many different kinds of tests, perhaps several requirements have been lumped together and should be separated.

    Bad:
    The user will be able to create, edit, delete, suspend, open, and replace all files which they have the necessary access to.
    Good:
    The user will be able to create a new file, as long as they have the Add File user right.

  3. Avoid ambiguity

    This is one of the most subtle and difficult issues in writing requirements due to its subjective nature. In order to achieve this goal the requirement must be clear and explicit, but care must be taken not to take this too far as the text can become unreadable and boring and this will defeat the core objective of requirements – in other words they are meant to be read by others.

    Bad:
    In order to delete a task the user must enter some details.
    Good:
    In order to be able to delete a task the user must enter a further password which grants them the rights to delete a task.

  4. Use definable and non-vague terms

    Many words used informally to indicate desired qualities are too vague for use in requirements. Vague terms include “user-friendly”, “versatile”, “flexible”, “Configurable”, “Approximately”, “as possible”, “efficient”, “high performance”, “quickly”, “modern”, “well designed”.

    Bad:
    The searching functions must be as efficient as possible.
    Good:
    The searching functions must return their results in no more than 10 seconds regardless of the size of the results.

  5. A Requirement must not be too high level

    A good Requirement is at a high enough level to be understandable and precise enough to be complete.

    Bad:
    The solution will have security.
    Good:
    In order to protect the data the system shall be subject to security by way of all users being required to enter a valid username and password combination in order to perform any function.

  6. A specification should not contain contradictions

    Care must be taken that requirements do not contradict themselves in their descriptions, nor contradict other requirements

    Bad:
    The system will be a 24x7 solution although it will normally be unavailable on weekends.
    Good:
    The system will be available 5 days per week through out the year.

  7. Requirements must be technically and legally possible

    There is no use in specifying requirements which are technically impossible or beyond the law as they will never be implemented.

    Bad:
    The system will read the mind of the user and determine which colour is their favourite.
    Good:
    The system will establish the favourite colour of the user by asking them pre-defined questions, in order to establish their favourite colour by process of elimination.

  8. Requirements must be necessary

    A good requirement should be a business necessity and not a wishful thought by an individual.

    Bad:
    It would be good for the solution to enable a user to add more than one property to an application, although only one property can be linked to an application.
    Good:
    A user can add only one property to an application.

  9. Focus on stating results

    Every requirement should specify clearly a single desired and achievable result.

    Bad:
    The printout will contain some text, although it is uncertain what this text will contain.
    Good:
    The printout will contain a list of users and their address details.

  10. Define verifiable criteria

    Every requirement must be verifiable. Often it is possible to indicate the method of verification by adding a simple phrase to qualify a basic need. This enables the requirements to be a good base for the acceptance criteria of the solution to be delivered.

    Bad:
    The solution must be designed in order to guarantee that all of “very famos company” staff will enjoy the experience of using the application.
    Good:
    The solution must be designed in accordance with the user interface guidelines specified by standards.

  11. Do not design the system

    Requirements specify the design envelope, and if too much detail is supplied the design of the system will begin prematurely. Sometimes this is unavoidable if a requirement is to design the solution in a certain way, which in effect locks the designers in to designing the system according to the requirement stating the design constraint. Specifying the design rather than the actual need often increases the cost of systems by placing needless constraints on design and development.

    Bad:
    The user entity will be made up of three tables. The user table will be joined to the role table via the user_role table allowing for a user to have multiple roles.
    Good:
    The data model will enable a user to have one or more roles.

  12. Looking at a requirement from developer’s point of view can assist in measuring its quality

    To see if a requirement statement is sufficiently well-defined, read it from the developer’s perspective. Mentally add the phrase, “call me when you’re done” to the end of the requirement and see if that makes you nervous. In other words, would you need additional clarification from the System Requirements Specifications author to understand the requirement well enough to design and implement it? If so, elaborate on that requirement before you proceed.

     

  13. Do not build in let-out clauses

    Requirements which contain let-out clauses significantly increase the risk of the requirement not being fully realised. They look as though they are asking for something definite but at the last moment they back down and allow for other options. Problems arise when the requirements are to be tested and someone has to decide what, if anything could prove the requirement was not met. Dangerous let-out word include “if”, “when”, “except”, “unless”, “although”.

    Bad:
    The login process will never take no longer than 3 seconds unless the system is busy.
    Good:
    The login process must not take longer than 5 seconds to complete at all times.

  14. Avoid wishful thinking

    Engineering is a real-world activity. No system or components is perfect. Wishful thinking means asking for the impossible. Developers will rightly query or reject wishful requirements. Wishful terms include “100% reliable”, “Hand all unexpected failures”, “Satisfy all users needs”, “Run on all platforms”, “Never fail”, “Perfect”, “Upgradeable to all future situations”, “future proof”.

    Bad:
    All web browsers will be supported including any future browsers without the necessity to change any of the code.
    Good:
    Internet Explorer 5 and above, Firefox 2 and above will be supported only on a Microsoft Windows operating system.

  15. Do not mix requirements and plans

    Plans are essential, but they do not belong in the requirements of a solution. Usually they are updated throughout the project life-cycle, where as the requirements should stabilize. Mixing requirements with plans tends to increase the requirements workload through extra revision and review meetings. Danger signs are references to dates, deadlines, project phases and development activities.

    Bad:
    The solution will begin as a desktop application but will be converted into a web application at some time in the near future.
    Good:
    The solution should be written so that a web version can utilise the core code without the necessity to re-write the core code.

  16. Do not speculate

    Requirements are part of a contract between customer and developer, with users as interested third parties. There is no room for “wish lists” – general terms about things that somebody probably wants. Danger signs include use of generalisation words such as “usually”, “generally”, “often”, “normally”, “Typically”.

    Bad:
    The solution will most likely be deployed on five servers.
    Good:
    The solution will be deployed on five servers.

  17. Do not express possibilities

    Possibilities are indicated with terms such as “may”, “might”, “ought”, “could”, “perhaps”, “probably”. If developers do what they have to, they will always ignore things that user might possibly require.

    Bad:
    At some point in the future the solution may need to be able to run on UNIX servers.
    Good:
    The solution must be able to run on servers with both Microsoft Windows and UNIX operating systems installed.

  18. Take care when using the word “Or”

    The word “Or” can often cloud or severely confuse a requirement and render it as un-verifiable due to the conditional nature of the requirement. Where “Or” is used, often this indicates that there are two requirements being joined into one.

    Bad:
    The user can download customer documents to their local machine or they can print the files.
    Good:
    The user can download customer documents to their local machine

  19. Avoid stating requirements redundantly

    While including the same requirement in multiple places may make the document easier to read, it also makes it more difficult to maintain. This results in the necessity to update multiple instances of the requirement at the same time to avoid inconsistency.

     

  20. Avoid jargon, abbreviations and colloquialisms

    Where possible avoid jargon, abbreviations and colloquialisms. Where jargon or abbreviations are used, they must be listed with their meanings in the project glossary.

    Bad:
    If a user enters their SAD, they will in effect be considered as top dogs of the system.
    Good:
    If a user enters their special authentication details, they will be considered as super users, which entitle the users to perform all functions.