How to create great deliverables

(printable checklist at bottom)

Purpose and objectives

The principle of Flow requires that work moves from left to right, quickly, and without impediment, and without being returned for rework.

But when work forms eddies, or, even worse, travels backwards, this impedes flow , and it is a signal that we did not do the work properly to begin with. Such issues in flow are cumulative as we move through the SDLC.

So how do we fix that?

When we consider that issues in flow primarily arise at the hand-off points between roles in the SDLC, it stands to reason that if we can improve those hand-offs, then we will also improve both velocity and quality in the SDLC, which is to say, we will improve flow.

In any kind of initiative at scale, irrespective of whether we are speaking of agile or waterfall, the key to improving the hand-offs is to improve the quality of the deliverable that occurs at the hand-off point.

Flow is accelerated when we have such consistent, well-defined, and high quality deliverables, not just at the point of product delivery to the customer, but at every hand-off point in the SDLC.

So, the purpose of this discussion is to enable the improvement of flow by:

Assisting the authors and editors of such documents to provide higher quality deliverables that move smoothly through the SDLC from left to right, without eddies and returns; and,
Assisting the consumers of such deliverables to have a standard definition of “what good looks like”, so that even before beginning work, they can be sure they have the material they need to do so.

Audience

If you are a person that is creating documentation in the SDLC for consumption by any downstream functions, then this material is for you.

If you are a person that is consuming documentation in the SDLC provided by an upstream role, for the purpose of creating your own deliverables, then this material is for you as well.

If you are new to software delivery, then this material will be a massive accelerator for you.

If you are an old hand that has already rewired your brain into the context of continuous and life-long learning, then this material will be useful to you as well.

If you have not already remodelled your approach to creating your deliverables, then this material is a blueprint for doing so.

Context

This documentation forms part of the Visionate Academy Advanced Agile Practitioner Toolkit. It places the material in the context of organizational culture, the Lean-Agile SDLC, and the quality assurance V-Model, as follows.

Cultural Context

In the context of the elements of organizational culture that enable effective delivery of software specifications, this item is a methodology guideline document, which, within it, makes reference to specific supporting elements of values, principles, policies, and standards.

That is, it is part of the ‘what’ which contains reference to the ‘how’, and the ‘why’.

Lean Agile SDLC Context

In the context of the Lean Agile SDLC the document applies for any role that is identifying or refining requirements for any downstream roles.

Although the domain of engineering has activities that fit this description, it is in the domain of shaping where the majority of this work occurs, and therefore it is the deliverables of the shaping domain that are the primary focus of this document.

V-Model Context

In the context of the quality assurance V-Model the document has application for all quality assurance audiences that must utilize SDLC documentation for the purposes of QA. The image below shows how shaping deliverables map directly to quality assurance deliverables that form part of the engineering domain.

Mindset

Mindset is the foundational part of organizational culture. It also identifies the purpose and objectives for operational practices.

The two elements that make up Mindset are values and principles.

Values are generally encompassing, but principles are purposeful statements of intent. Values and principles can apply at multiple levels from the individual level, through the team, through the discipline, through the unit, through the company, and through the society at large; perhaps even all of humanity, although that is arguable.

In our context we are examining values and principles that apply to the enablement of flow.

Values

We have invented no values.

There are multiple value sets which exist in global reference models, and which are more or less related to each other. In this material we have aligned to values adopted from the scaled agile framework (See https://www.scaledagileframework.com/safe-core-values/)

Built-in Quality
Program Execution
Alignment
Transparency

Principles

Scaled agile also has a set of principles, which, if you have not already assimilated them, are well worth the time spent learning (https://www.scaledagileframework.com/safe-lean-agile-principles/ )

We are generally aligned to the above; but for our purposes in terms of authoring documents to enable flow, we also have some more specific principles, as follows:

Analysis and Specification are different things
Separation of concerns
Your customer is downstream
Targeted to the purposes of your audience
Do the least work possible
Comprehensive, but lean
Not finished, until validated
Focus on finishing, not starting

Analysis and Specification are different things

Analysis is what we do to inform our understanding enough to create a specification for the next role downstream.

Analysis documents are for our own use, or to validate concepts with stakeholders. Specifications are what we provide to our downstream customers. These are separate artefacts.

Separation of concerns

Know what you are creating and why.

When we are working in the SDLC our job is not to ‘fill a role’ or ‘perform an activity’; our job is to create deliverables for specific purposes.

For any particular role, and at any particular node, there may be more than one audience and more than one deliverable. We must understand the differences and keep concerns separate.

For example, there is no point in loading up a deliverable intended for a solution architect by documenting a decision point in the business that has no relevance to solutioning. Similarly there is no point in filling up a change specification, intended for a systems analyst, with a discussion on changes to business processes that are not part of the technology specification.

Your customer is downstream

Understand that your customer is not necessarily the core stakeholders you are verifying your documentation with; your customer is the person in the role that is consuming your deliverable.

Targeted to the purposes of your audience

Our documents must not be created to meet our needs, they must be created to meet the needs of the downstream customer. As the ‘sender’ of the communication, the burden of responsibility for the communication being properly received and understood is on us, not on the consumer of the communication.

Do the least work possible

This sounds counterintuitive. Aren’t we meant to all be working hard?

Doing the least amount of work necessary is related to the notion of simplicity and the notion of focus. When we stay focused and keep our deliverable as short and sharp as it needs to be, this brings large benefits.

It reduces the effort and cost for our own activity
It reduces the effort and cost for people that need to verify, validate or use our deliverable
It reduces total cost of ownership because it is easier to maintain over time
It improves quality because our deliverables are easier to understand and validate

Doing the least work possible does not mean cutting work short; it means staying focused on the work that absolutely needs to be done, prioritizing that work, and delivering it.

“Make everything as simple as possible, but no simpler.”
Albert Einstein

Comprehensive, but lean

Our documents must be comprehensive and contain everything required by our customer, but not one word more than that.

When we fill documents up with ‘things we know’, or empty words to fill in a template section, or repetition, we increase the burden of understanding, which leads to lower quality and lower velocity. It is anti-flow.

Not finished until validated

As the authors of documentation, we are not the ones that can call it complete. It is not complete until it has been validated and accepted by our customer. Customers, i.e. downstream roles, have the right to reject our documents if they do not meet their needs.

Focus on finishing, not starting

In the same context as the above, when we receive input from upstream roles, we have an obligation to validate the specification before we begin to act on it. We must never start work that we cannot finish.

Practices

The checklist documentation is arranged in terms of numbered policies and associated standards that apply

Language & Content

1. Must be Comprehensible

Is the terminology and prose jargon free and understandable by the implementation team, business stakeholders and future maintainers of the system?
Every business has jargon, and different units within the same business can even have their own jargon. Use of jargon places barriers to communication and runs the risk of making assumptions of shared understanding. The barrier forms because people may not understand the jargon; the risk is because people may have a different understanding of the jargon than what was intended by the specifier.
Where there is a compelling or practicality-based need to use jargon, then a case could be made for it provided that all elements employed are defined and referenced in a glossary.
In most cases, however, jargon is unnecessary and can effortlessly be avoided by the use of standard English. This approach ensures that concepts are clearly communicated in plain language that all stakeholders can interpret the same way.
Frequently, jargon is employed for social reasons. For example, to prove that one understands the industry and can proudly display their hard-won knowledge. In this case, the use of jargon is motivated by vanity and must be avoided.
Another reason to avoid jargon is that it can conceal an actual lack of clarity and understanding, or an unwillingness to do the work to explore an area of design.
In many cases when techno-speak or jargon is challenged, the deliverable specifier will say ‘I’ll get back to you on that’. If the deliverable specifier cannot immediately describe what the item means, chances are that more work needs to be done which should have already been done up front.

2. All Terms Defined

Is the document free of undefined concepts, terms, and acronyms?
This is related to the discussion on jargon under the Comprehensible rule. Any terminology employed must form either a part of a glossary, or be specifically defined in the document itself. Readers cannot be expected to understand the meaning of terminology that is undefined. When the deliverable specifier expects the reader to have this understanding, this is what we term an assumption of shared understanding.
As with jargon, the risk here is either that the reader will not understand what is being discussed, or the reader may have a different understanding than what was intended by the specifier. The latter situation is much worse because it can go undetected for longer.
The issue is completely avoided if we adopt a disciplined and professional approach to the definition of terms.

3. No Synonyms

Is the document free from the use of synonyms? Or if synonyms are employed, the usage is clearly identified (e.g. “The terms ‘container’, ‘box’ and ‘unit’ are used interchangeably in this document”)
The usage of synonyms is commonly taught in schools because language flows better when repetition of the same word is avoided. We are therefore conditioned in this usage and for that reason many deliverable specifiers will use a multiplicity of terms to effectively refer to the same thing.
The problem with this approach is that if a document contains two terms that are not clearly associated as synonyms, then the usage forms a barrier to communication and can result in defects.
For example, “The operator gives the docket and the weight card to the supervisor. When the docket has been processed by the foreman, the operator takes the docket to the truck driver, picking up the driver’s lunchbox on the way.” In this example the supervisor and the foreman are the same person, as is the truck driver and the driver. Referring to them by different terms leads to avoidable confusion.
In the project context, the awkward sounding repetition of the same wording for a single concept is by far the recommended approach. It is best to avoid the use of synonyms altogether but if they must be used, we must ensure they are clearly defined as such.

4. No Ambiguity

Is the document free from ambiguity in any of the statements (i.e. operations, rules, definitions, etc.)?
Ambiguity can arise in a number of ways.
It could simply be as a result of an incomplete description or it might be an English language sentence that does not make sense.
It might arise due to the use of pronouns where multiple parties are referenced. For example, “The operator gives the docket and the weight card to the supervisor. When the docket has been processed and the weight card data entered into the system by the supervisor, he takes it to the truck driver, picking up his lunchbox on the way.”
In the above example the identities of ‘he’ and ‘it’ in the final sentence are not clear and neither is the ownership of the lunchbox. Even though the resulting sentence may sound awkward, it is better to avoid the use of pronouns and to use nouns (i.e. names of people, places, and things) to describe people and items.
For example, the following is an improved sentence:
“The operator gives the docket and the weight card to the supervisor. When the docket has been processed by the supervisor and the weight card data entered into the system by the supervisor, the operator takes the docket to the truck driver, picking up the truck driver’s lunchbox on the way.”

5. Defined Lists

Are the relationships in lists clearly defined and free from ambiguity?
Ambiguity can also arise from bulleted lists where the relationship between the bullets is not clear, i.e. are they an ‘and’ relationship, or an ‘or’ relationship, or a combination?
We can deal with this by using the words ‘and’ and ‘or’ explicitly in lists, and by splitting out lists to enhance clarity rather than including all statements in a single list.
Consider the follow examples :

An order can be accepted under the following circumstances:

The customer is in good standing in the system, i.e. no bad debts
The sum of outstanding unpaid invoices does not exceed the customer’s credit allowance
The credit supervisor has overridden the controls and allows the order to proceed.

In the above case the relationships are unclear and can be improved by the addition of ‘and’ and ‘or’, as follows

The customer is in good standing in the system, i.e. no bad debts; and,
The sum of outstanding unpaid invoices does not exceed the customer’s credit allowance; or,
The credit supervisor has overridden the controls and allows the order to proceed.

But this is still not perfect because the rules remain inexplicit. The following is a better approach that makes the rules explicit.

The customer is in good standing in the system, i.e. no bad debts; and,
Either:
- The sum of outstanding unpaid invoices does not exceed the customer’s credit allowance; or,
- The credit supervisor has overridden the controls and allows the order to proceed.

This makes it clear that the credit supervisor has the ability to override the credit allowance, but does not have the ability to override a situation where customer standing has already been affected through bad debts.

6. Verbs – Action Verbs

Does the functional flow use only action verbs to describe the flow?
Action verbs express something that a human or system actor can actually do. For example, “At this point the painter must paint the fence green.”
This is in contrast to the use of stative verbs which describe a state, situation or condition. For example, “At this point the fence must be painted green.”
Action verbs are preferred because they link the actor to the action without any ambiguity.

7. Verbs – Allowable Auxiliaries

Is the document free of all disallowed auxiliary verbs?
Allowed and recommended auxiliaries are ‘will’ and ‘must’. For example, “At this point the painter must paint the fence green.”
Disallowed auxiliaries are ‘can’, ‘could’, ‘may’, ’should’ and ‘would’. For example, “At this point the painter should paint the fence green.”
The disallowed list is prohibited because none of them are an instruction.
They are all, to one extent or another, conditional and therefore inconclusive. The verb ‘should’ is the worst culprit and must be eliminated entirely from the specification vocabulary.
The inclusion of conditional language in a specification detracts from clarity, unless the condition is based upon a business rule which is clearly articulated, with all branches identified.

8. Acronym Usage

Are all acronyms defined in the glossary and expanded in full at least once per page?
The first time an acronym is used on any particular page, we must write it out in full with the acronym shown in brackets.
For example: ‘The Central Intelligence Agency (“CIA”) was responsible for more than half of all UFO sightings in the late 1950s and most of the 1960s — but those weren’t little green men flying high in the sky, they were spies.’
It is not enough to mention the acronym once in a glossary or once only at the start of a document. This interrupts the comprehension because readers must flick backwards and forwards through the document to enhance their understanding. This is particularly important where a large number of acronyms are employed in a discussion and are peppered through a single paragraph.

9. Consistency of Content

Is the content consistent internally and externally (i.e. not in contradiction with other design documents)?
The deliverable specifier must maintain consistency within their own document, and when necessary, coordinate with other deliverable specifiers to confirm consistency of design across end to end processes.
This ensures that the design fits into the bigger picture and we avoid situations where one design ‘breaks’ functionality in other areas.

10. Pertinence

Is the design free of irrelevant, extraneous, and unnecessary information?
Non-essential and peripheral material included in a specification is a recipe for confusion. The specification document is not a place where the deliverable specifier can cram in everything they might happen to know about a particular subject, it must be focused on the outcome being pursued, i.e. on the specification.
Implementers need a clear and explicit set of instructions and nothing else. The minute implementers start ignoring sections because they do not appear to be relevant, a significant opportunity for error is introduced – see the Precise and Concise rulefor more on this.

11. Comprehensiveness

Are all necessary events, conditions, operations and exceptions defined to the level needed for implementation to proceed?
The design must define the entire scope of what is to be built and this scope must explicitly be documented (note: See Pertinence rule).
If something is not designed for, the specifier cannot expect that it will be implemented.
An exception to this is where there is an existing and published standard that implementers have been trained in and are aware of. For example, “All company web pages must adhere to the brand standards.”
In the absence of any such standard, it is a failure of design to encounter a situation where implementers ‘should have known’ what they were expected to have done. If this occurs, it is due to the erroneous assumption of shared understanding.
Note: The ability to judge whether a design is comprehensive is aided by following the Precise and Concise rule. A slim document containing only what it must is much easier to assess for missing items that is a padded and obese compendium.

12. Correct Level of Detail

Does the specification satisfy the level of detail required by the implementation team? Have all operations been stated in terms of their triggering events or conditions, information requirements, processing and outcomes?
This is related to the rule of Comprehensiveness, specifically to the level of detail necessary for implementation to proceed. The level necessary means getting to the correct level of detail and no deeper.
It is an error for deliverable specifiers to interpret this to mean that they are required to provide technical detail – they must precisely avoid doing this. See the Avoidance of Technical Bias rule.
Rather, what is meant by the correct level of detail is the right level of business detail. It is not a question of requiring deliverable specifiers to be technical; it is a question of ensuring that they have fully documented all aspects of the business flow.
Time pressure is no excuse for lack of detail. All this does is shift the problem downstream because the implementer will be forced to make multiple trips back to the deliverable specifier to get clarity, or they may attempt to go directly to the business users themselves or worse yet, make their own mind up about what to do.
In determining the correct level of detail to arrive at, the following rule must be followed:
If the deliverable specifier deems it acceptable for the implementer to decide how to deliver a particular detail, then the specifier does not need to elaborate on this point in the specification.
If, however, it is critical that the detail be delivered in a specific way, then the specifier must articulate this in the specification so that it is clear for the implementer.
In this sense, all details that the deliverable specifier deems to matter, should be clearly articulated in the specification. Details where they are happy for the implementer to make their own mind up do not need to be included – but the specifier cannot complain about such decisions later on. It is a matter of, speak now, or hold one’s peace.

13. Precise and Concise

Is the specification precisely and concisely stated?
Padded content, waffle, and rambling detract from understanding in a number of ways.
To begin with, such content is confusing – readers will try and interpret it to extract something that is actually relevant or real. Eventually, if they are sufficiently confused and cannot latch onto something relevant, they may form incorrect interpretations. This wastes time and can lead to defects in the end product.
An unduly padded document is also larger and therefore more imposing for readers. The result of this could be a rushed effort to digest the information. With insufficient time to comprehend the material fully, we run the risk of having the reader not comprehend the document as a whole and miss vital information.
Presenting the reader with a daunting document also ‘trains’ readers to ‘ignore’ information in their effort to speed up the assimilation of the material. The choice of what information to ignore is subjective and this can lead to vital information being disregarded.
These issues can be avoided if the specification is checked to ensure that every single line and word is in place for a specific and known purpose. All readers of the document can then be confident that absolutely everything in it is there for a reason and must be taken into account.

14. Free of Content Repetition

Is the specification free of content repetition?
Content repetition means repeating the same description or rule in multiple places; it is a particularly undesirable form of padding.
When a deliverable specifier documents the same business rule or instruction in multiple places, it introduces the same issues associated with padded content that were referenced in the Precise and Concise rule, but the issues do not end there.
In addition, such a practice adds to the maintenance burden of the document, and we run the risk that the instances of this repeated content could fall out of synch when updates are made.
When an element of the design changes and this content needs to be updated in multiple places, there is a good chance that one instance will be overlooked. The result being that this instance will continue to convey old and conflicting information. This increases the likelihood of defects in the end product.
Where the content being repeated is a description of a concept or definition of a term, it is preferable to use the glossary section to define the term/concept once at the start of the document. Similarly, business rules or other elements of design should be captured once in a table and referenced later in the document. Alternatively the specifier could employ the powerful cross-referencing functions commonly available in leading word processing applications. Guidance is available online for the use of such features.

15. Defined Context/Value

Is the context of the design outlined to the extent (and only to the extent) that it is comprehensible within the bigger picture?
If implementers do not understand where the specification fits into the wider scheme, they do not understand its importance or how it might possibly be flexed to fit when they run into issues.
Providing this context can help implementers be more proactive in highlighting technical design choices that might not be worth the effort of implementation in terms of cost and return.
By contrast, requiring implementers mindlessly to deliver exactly to the defined specification can lead to relatively unimportant areas being invested in, to an extent that far outweighs their importance.
Note: In creating this context, deliverable specifiers must adhere to both the rules of Comprehensiveness and Pertinence. Loading up documents with irrelevant content is also an error.
It is critically important that specification, i.e. instructions, are not included in contextual sections of documents, and that it is clear to the audience that this is the case. Failure to follow this rule can lead to implementers incorrectly extrapolating design from context, thereby introducing bugs.

Format & Structure

16. Consistency of Format

Is the format consistent with a standard approach to functional design?
Consistency in documentation is an aid to clear communication. Keeping the documents consistent has the real effect of fewer defects in the end product.
It is the responsibility of the communication sender (i.e. the deliverable specifier) to ensure clear communication; it is not the responsibility of the receiver (i.e. the business stakeholders and the implementers) to make sense out of inconsistent communications (i.e. documents) provided to them.

17. Compliant

Has the document been rendered in the agreed format and does it adhere to agreed standards?
This is an adjunct to the rule of Consistency of Format. Adherence to this basic level of discipline enhances the use and understanding of the design, which is why compliance to standards is a basic part of the verification process.

18. Document Tidiness

Is the overall document presented in a tidy and well laid out manner?
If the document is hard to understand, disjointed or messy, then it is an indication that the specification was rushed and is likely to be error-prone.

19. Document is Instructional – Not a Status Review

Is the document set up as a series of specific flows and/or instructions and not as a simple information dump that the reader is meant to interpret?
This rule ensures we avoid errors common in documents where the deliverable specifier has not fully detailed the functional flows or business rules. In such cases, rather than present this information in a flow, the specifier choses to deliver content as a tabulated dataset often in a spreadsheet format. The risk with this approach is that the functional flow is not clear and the dataset requires interpretation by the reader.
Tabulated data is acceptable where the design calls for data mappings or lengthy lists of items such as error messages. However, spreadsheets and tabulated data must not be used in place of functional flows or business rules. These elements must be explicitly detailed in an instructional manner as a flow, showing alternate and exception flows. Failure to explicitly include this content means that the implementer will be forced to infer the functional flows. This is not acceptable and should be considered a failure on the part of the deliverable specifier.

20. Assumptions Stated and Taken into Account

Are assumptions stated clearly, in one place only and not scattered throughout the document? Are assumptions valid? Are assumptions that are defined actually taken into account in the specification?
It is acceptable to have assumptions in the specification, provided that their legitimacy has been investigated and their inclusion is not just a catchall for analysis work that is incomplete.
The practice, however, of scattering assumptions around in a document renders them easily missed. Assumptions must be in their own section of the document and in one place only.
In addition, only those assumptions that are actually relevant must be included. Irrelevant assumptions just confuse the reader; so the rule is – only include assumptions which are relevant to the design at hand.

21. Conflict Free

Have we ensured there is no conflict with given or stated assumptions or constraints? For example, business environment, standards, technical environment, cost, schedule, and resources?
This ensures that the design fits into the capability and scope of the project.

22. Completeness

Is the document fully defined and in a complete and published state?
Have all undefined, unresolved, or incomplete instructions in the specification been resolved and/or identified for re-specification to the extent required by the project methodology?
As a rule, the specification must not be released to implementers until it is entirely complete and ready for publication. Releasing unfinished specifications can lead to time wasted in the implementation activity. It can also lead to the introduction of defects or sub-par technical design due to implementers working from incomplete information.
On occasion, it may be the case that a specification is released to implementers in an incomplete state, but this must be by exception, not the norm. Such a case may be when project necessities have required a fast-tracking of design and implementation, and an early release has been agreed and approved.
If the specification is not complete, then the release must state this clearly and there must be an agreed process for getting it completed; we cannot just leave it as is.

Technical Content

23. Defined Business Objects

Are all business objects fully defined and explicitly and cleanly described along with their relationship to other objects?
Implementers do not necessarily demand that deliverable specifiers get all the way down to a conceptual data model in their design documents, and indeed will resist and complain if the specifier imposes a novice effort.
Nonetheless, regardless of whether or not the deliverable specifier is an accomplished data analyst, they must at some level or another cleanly, explicitly and accurately define the objects – at a business level – that are being acted on in the design, and they must also explicitly define the relationships between such business objects.
This information is often documented in the supplementary information accompanying the functional specification.

24. Alternate Flows Correctly Sized

Is the document free of unwieldy alternate functional flows? Have any such flows been split out to a separate document?
In the use-case approach, when an alternate flow itself contains alternate or complex exception flows, then we must consider it as a separate design document.
- In the use-case approach these must be created as separate use-cases of type ‘includes’ or ‘extends’. The reason for this is to ensure that the documentation does not become so complex as to introduce confusion and form barriers to comprehension.
Where such a separate use-case defines a process that is called upon only by the ‘parent’ use-case being worked on, then the relationship to the new use-case is ‘extends’. This means that the new use-case simply extends the functionality of the parent case.
Where the separate use-case is a general case that can be called upon by more than one ‘parent’ use-case, then the relationship is ‘includes’. This means that the parent use-cases call upon (i.e. includes) the functionality of the separate use-case.
- Extends example:
  - Parent case:
    - Paint Fence
  - Extends case: (Used only by ‘Paint Fence’)
    - Prepare Fence Surface for Painting
- Includes example:
  - Parent cases:
    - Paint Fence
    - Paint House
  - Includes case: (Used by ‘Paint Fence’ and ‘Paint House’)
    - Select and Hire Painter
The above discussion applies irrespective of whether we are documenting with use-cases, user-stories, or some other means of documentation

25. Free of Technical Bias

Is the specification free of technical implementation bias (i.e. not restricted to a specific technical design option?)
error for the specifier to refer to them in specification.
In this context we define the above terms as follows:
Solution Architecture
- Defines what technology will be used for a particular purpose.
- For example, SAP Process Integration (PI) will be used to intermediate between SAP and external trading partners.
Technical Architecture
- Defines what best practices and standards must be used for a particular technology area.
- For example, all data access will be by means of precompiled stored procedures with no direct SQL access to the database.
Technical Design
- Defines how identified best practices and standards will be assembled to deliver each particular unit of specification.

26. Low Probability Items Included

Does the document include all alternate or exceptional flows regardless of their probability?
This is called the ‘It will never happen’ error. Regardless of the probability of something occurring, if it is possible that it could occur, then the system needs to be designed to handle it. Failure to cater for such cases results in users being exposed to system errors that are not handled gracefully and which cause the application to crash. It is no good saying after the fact ‘The implementer “should have known…”’ It is the responsibility of the specifier to articulate these scenarios in the specification.

27. Process Flow Diagram

Does the process flow diagram, if included, reflect the textual description of functional flows?
One of the reasons not to include process flow diagrams is because on their own they are not enough to express the design, and yet their inclusion requires another level of maintenance, along with the textual description of the flow. In effect it breaks the Free of Content Repetition rule. If the textual description of the flow changes, the process diagram must also be updated, or the content will fall out of synch and cause confusion.
There are situations, however, where a process diagram adds context and clarity and in those cases the check is to ensure that it matches the text in the document.

28. Separate Documentation

Are all specifications created as separate documents that can be accessed, printed and managed separately?
The more traditionally minded deliverable specifiers resist this rule. Many deliverable specifiers prefer to consolidate documents ‘in one place’ so that they are all accessible together. The same deliverable specifiers will be the first to complain that business stakeholders do not read their documents and that the implementers always seem to be confused.
The reality is that from a business perspective, small, slim, focused documents are easily read and understood. From a technical perspective, a modular and complete instruction set for a particular piece of development is comprehensible and can be acted on in the knowledge that every word is relevant and must be implemented.
Large omnibus documents by contrast are skimmed over by the business stakeholders and are confusing to implementers because once again we are training implementers to ignore instructions. This is the opposite of what we want to have happen, so we must avoid it.

29. User Interface

Is the user interface defined to the extent that the user cares?
If the users are extremely sensitive about the user interface look and feel, a prototyping specification is probably better than a documented design.
In most cases, however, users will care about screen flows and the general position of elements on the screen and how they are validated, but they will not be as concerned with the specific details of the user interface.
In many cases a user interface (wireframe) does not warrant inclusion in the document, but where there is a sizable element of human user interaction then wireframes ought to be included to the extent that the user cares about the detail.

For a printable checklist – download here