We worked closely with the System Architect (SysA), the software Product Owner (PO), the software team and some other involved people. Early workshops showed a deep discomfort among the developers concerning the requirements and specifications.
- Too many documents in an unclear state
- One document covers content and requirements ranging from high level down to small details depending on the know-how of the writer, but overview and context are missing for the reader
- Which documents need to be up-to-date?
Too many documents in an unclear state
We found different requirements documents for different project stages with different authors (see Figure 1). The landscape of existing document types was complex, sometimes overlapping, with some gaps and all of them in a style developed years ago in a waterfall context with customer requirements specifications, system requirements specifications, and many more Word documents. Some central documents were required to pass a project gate but the quality criteria were unclear; the later use in the product development project depended on the people in the project. No requirements management beyond versions of a Word document was established. The requirements abstractions were mixed throughout the documents: in the customer requirements document (CRS) high level and very detailed requirements were side by side in a long list of requirements.
There is some information that is important during the project at some stage, but it is typically not of any further interest as soon as the project is in another phase or finished. Other information, however, should be kept up to date and may be of value after the project. How do we decide which is which? We asked the team which information would be helpful for them when they need to start with a minor release version, say version 2.3, of an existing product. Where do they look for the information now, and how could we organize it better?
With this guideline we structured the “document landscape” into product-driven documentation and project-driven documentation and added new types like coding principles and code comments to our landscape, as they also document important aspects of the product. Figure 2 illustrates an example.
Documenting different levels of requirements
The documents were typically associated with a certain level of details even though the documents of the current project did not fit the expectations. It was important to understand which people in the company have the domain knowledge, and at which detail level. The product manager is not the expert of the so-called “system check” that the production line needs for validating the built system, but has to know:
- that the system check is needed for the product,
- whom to ask, and
- that it is needed for the milestone “production-ready”.
Together with the Software Team Leader, the Product Manager (PM, a member of the marketing team) and the Product Owner (PO, a member of the software team) we structured the requirements levels as needed and based on the landscape of documents, and we found a gap that had led to many discussions between the Product Owner and the Product Manager. We bridged the gap by introducing the feature tree: the feature was the right level to hand over from PM to PO, while the tree was the structured view on the features. For the transition see Figure 3.
From a requirements level’s point of view the feature builds a bridge between the user stories of the software project’s world and the product user’s view. Each feature has its stakeholder(s): they are involved in the specification of acceptance criteria and testing and ensure adequate quality.
The feature description is often represented in table form based on a company-specific template: some items are general feature description items or fields (e.g. see Table 1), some are company-specific items.
|ID & Name||nnn xxxxxxxxxxxxxxxxxxxx|
|Class||Core, Base, Feature|
|Pre-condition||Feature reference, states|
|Stakeholder||[Who delivers details and tests]|
|Feature size||[S, M, L, XL]|