Chapter 8
Master Server Requirements—round one

This is early draft material, barely more than a stream of consciousness and notes.

We will take a more general look at requirements in Chapter 9. Before diving into requirements we should first think about why we want them. We start with a need, usually in the form of a problem, usually a problem blocking progress toward some goal. In our current situation;

  • “The master server must have Salt installed”
  • “We want SSH installed so we can log on in order to control the Salt master”

These are questionable requirements as they specify technical solutions. However this is to be expected in a technical domain. Arguably we could step back and express the first requirement as “I need a way to manage the system configuration”, but this feels unnecessary at this point.

Before finalizing these requirements though we have others to satisfy;

  • “I need to store documents”
  • “I need to be able to identify specific versions of documents”
  • “I need to be able to build and test versions of the system”
  • “I need to be able to control different environments”

In other words our project needs some document management before anything else.

From these high level “needs” we need to derive requirements specific enough that our development team can implement them. This is a rather vague statement, but necessarily so because the amount of effort required will vary according to circumstance.

If we are specifying requirements internally (developer specifying the build system for use by the development team, for example) then we need to invest less effort than if we were writing requirements between different organisations or parts of the business (the marketing department writing requirements for a new campaign management system to be implemented by an external development agency).

8.1 What are requirements for?

For now, let’s limit ourselves to basic technical requirements. Why write requirements?

Short answer; communication.

Requirements communicate information between the person who needs something to the person providing that something. Ideally this communication is unambiguous and complete. That is, the provider never asks the questions, ‘what exactly does this requirement mean?’ or ‘what else do you need?’. Nor does the requester feel the need to ask, “can we just add…”

As you might imagine this means requirements vary considerably in their complexity. On a one man project it is common for no requirements to be written. There is no communication problem, as both the requester and the provider are the same person the requirements can change without notice, there is no need to be specific, there is no problem of ambiguity (or at least the resolution of ambiguity are simple).

On a project with multiple participants the need for clear, durable communication increase in proportion to the number of participants. One requester and one provider can likely be dealt with informally. Projects tend to be small and communication can be as regular and close as the two participants desire. Once several requesters are involved it becomes essential for the provider to ensure that there is consensus among the requesters. Failing to do so is almost certain to degenerate into chaos as disagreements among requesters drive the provider mad as they pull in different directions.

These communications are compounded further when multiple providers are involved (exponentially so when those providers work in different organisations).

Communication operates over space and time so although it may seem pointless to document requirements when only two or three people are involved remember that in future you may be dealing with more people (not to mention the future selves of the original participants). These ‘future participants’ may benefit greatly from well documented requirements (not to mention the history of decisions made in reaching those requirements).

If you’re working in a team these requirements help to ensure everyone is working to achieve the same result. I think of requirements as guiding lines that specify the essential properties of the system. Within this specification we have plenty of room to be creative but when all is said and done we must meet this specification before all else. These requirements help ensure we are not wasting resources on unnecessary activity.

I want to stress here that looking back on these requirements we may see violations. This is because requirements change. It is likely that the requirements the project has now will change as the project progresses, so we expect the system to sometimes violate these early requirements. This is not a failure on our part, it is simply the way the world works; you cannot see beyond the horizon.

Right now our project needs:

  1. A central repository for our:
    • changes (issues etc.),
    • documentation,
    • code, and
    • configuration.
  2. A means of deploying configuration (build out of machines, ensuring those machines remain consistent with project needs, etc.)

The central repository does not have to be one repository, but should be accessible to all members of the project team.

The current requirements are all technical and focussed on the system development support system. There is a low communication barrier between the customer and the development team (they are basically the same in this context).

We are fortunate that we have no operational constraints at the moment. If we had an operational environment to think about we would need to account for this in our requirements. Perhaps taking in documentation and instructions about how to deliver into production, starting the liaison with operations (getting suitable representatives from operations on the project to ensure that whatever we intend to deliver will be acceptable).

8.2 Uses of requirements

Beyond their function as an aid to communication requirements have other functions.

8.2.1 Requirements as contract elements

Requirements often form a part of a contract for delivery. This often leads to people insisting on the need for a ‘complete’ set of requirements (and the resulting interminable, and often flawed, requirements phase). After all, if the requirements are not established in excruciating detail beforehand, how can we price up and control the project?

Quite simply you cannot, but then again, even with these painfully acquired detailed upfront requirements, most projects

citation needed fail to deliver. Why? Because requirements change, especially in light of experience. Also, people are better at telling you what is wrong with the delivered system than they are imagining what they need up front.

Which is more productive? Do something quick and realise it’s wrong, correct course, repeat. Or, spend months trying to get things perfect, develop something based on the wrong requirement, deliver something that does not meet the user’s needs but damn it meets the requirements. This was realised long before computers were created; models, proofs, and prototypes are all attempts to provide customers with something concrete to evaluate and critique before committing to expensive production runs. While these prototypes etc. where intended to be disposed off current IT development encourages continual refinement; taking each product and refining it through a deliberate process (in Agile approaches this is the often misunderstood1 ‘refactoring’ process).

8.3 How to capture our requirements

The majority of our requirements will be technical. Our users being technical too. That said we will have plenty of non-technical people too; programme office team, often project management is non-technical (or at least not deeply technical). There will also be plenty of people who require information from your project (or providing to your project) that will not be technical; customer, users, human resources, etc.

For now we are focussed on the project internals.

There are myriad ways to capture and control requirements from simple text files to dedicated software management systems. You may be compelled to use a specific solution (company standards) but for this project we have free rein. Guided by the idea of maintaining simplicity until we need to make things complex we will start with text files. If future demands require that we use a more complex system for managing our requirements we should be able to reformat them relatively easily (generally I find it easier to move from simpler formats to more complex).

Eliciting and decomposing requirements is a skill unto itself (just take a look at the may books on the topic; search for ‘requirements’ or ‘business analyst’). But we’ll have a stab at a simplified version.

There are a few things we can be fairly sure about. We need a way to store documentation (including these requirements). The documentation needs to be accessible. Members of the project need to be able to read and update documents. We want to be able to track the history of these documents. We need to be certain that documentation is controlled and accurately identified. I prefer a layered approach to document control.

  • Latest release.
  • Current draft
  • Version control repository

The latest release is the document from which the project must work. It is read only and published for everyone to access.

The current draft is a utility so that the author can access the document. This copy is only required for non-technical authors who cannot (or will not) use the version control repository. This copy may be unnecessary in many projects but my experience has been that it is often a fruitless task to try to get everyone using a version control tool when they have been used to using a shared file system.

The version control repository holds the complete history of all documentation on the project. Depending on the tool used and the nature of your project or organisation you may need to have more than one repository. Some documents may be confidential or restricted. It may be unacceptable to your organisation for these documents to be at risk of exposure (even to other team members—examples include contract and other legal documents, details budgets and costs). My opinion is that project documentation should be release as permissively as possible.

To be clear, the version control repository need not be a specific tool. It is possible to hold all documentation in a set of directories, using file name conventions to maintain a version history.

You should be realising at this point that our requirements need not, and arguably should not, say anything about the final solution (exception being where such a solution is externally imposed).

8.4 Starting a conversation

The core to eliciting good requirements is having good conversations.

This is the function of ‘stories’ in the Agile method. Stories are a useful formalisation of conversations between requesters and producers.

Once these conversations, and consequently the associated stories, are mature enough (notice, not ‘complete’, they are never really complete), we are ready to formalise these stories into requirements. (On projects where Agile is being fully implemented—a customer advocate is on hand—the story may be appropriate as a requirement.)

This is an oft repeated error. Stories are generally not good requirements! They are close, but win no cigar. A story will typically yield more than one requirement. Not all requirements will have a story, but some requirements may lead to a story being generated if the development team need to clarify something (this clarification may lead to yet more requirements).

Stories have acceptance criteria, these are the closest to requirements.

8.4.1 Traceability—sexy!

Before we get too far into this let’s talk about traceability. One of the problems faced by a project of any size is traceability. How do we know that we have done the right thing and that we have done everything asked for and only the things asked for2?

For any given piece of the final system I want to be able to say, ‘this feature was requested in requirement xyz’. If I cannot answer this basic question then why does this feature exist? Why did we expend resources to create it? Why did we adopt the cost of maintaining it?

All the cycling through requirements and stories in §8.4 leads to a history for requirements, this is another dimension of traceability.

If you work in a regulated environment you will find a need to maintain detailed audit-able traceable records. Generally, the more regulated your environment the stricter your traceability requirements. That said, regardless of any external requirements your project will benefit from effective traceability.

Traceability requires that we clearly and unambiguously identify each project asset. Identity schemes are an extended topic, there are as many schemes as there are projects (or so it often seems).

8.5 Testable requirements

Requirements must be testable. Some guidance suggests requirements must be SMART (Specific, Measurable, Attainable, Realistic, and Testable and Traceable). I suggest this is a reasonable guideline but, as with most advice, you need to intelligently apply this guidance. Remember, guidance is not law.

We can test manually or automatically; automatic testing is vastly preferable for the simple reason that automatic tests are more likely to be run and run more frequently.

8.5.1 Features versus design

Ousterhout [Ous19] suggests that Test Driven Development (TDD)3 is harmful because it results in ‘tactical’ development rather that ‘strategic’ design decisions. This largely depends on how you interpret TDD. If you treat TDD as automated specification verification then it’s efficacy depends on the specification. If you specify (requirements) at a design level then TDD will work well. It is true that, as presented by most advocates, TDD will result in technical solutions. I’m also sympathetic to Ousterhout’s promotion of design over features.

8.5.2 Test automation

If we can write tests to confirm our requirements have been met, and then automate those tests, we are golden. These automated tests can be run repeatedly as our project moves forward, acting as a ratchet, preventing any backsliding.

8.5.3 Tests we cannot automate

Some requirements cannot be automated, or it may be impractical to automate them. For example, aesthetic design requirements are often subtle and a matter of opinion. They are important, but practical impossible to automate. Even if we somehow establish a baseline (say record the GUI and save this as a ‘gold standard’, then replay the tests and compare the result to this gold standard. Fine, but even a light change to the GUI will throw this comparison out and we will have to manually assess a new gold standard. Repeat this too often and the automation of tests start to lose its usefulness.).

Although we may not be able to perform a test automatically it is worthwhile setting things up so that test results are confirmed automatically (making this confirmation a condition of passing the product). For example, we could maintain a spreadsheet where each line holds a manual test and next to that test the latest result, we can then write a utility to ‘test’ that all the result fields are ‘pass’ before declaring the product ready for the next phase.

1I say ‘misunderstood’ because too many fail to treat refactoring as a definite step, instead muddling it it with development of new features.

2Delivering more than requested means we are ‘giving away’ project resources.

3A development methodology in which tests are written before the implementation code.