Chapter 10: Use Case: The Camford University Paper Publishing System

In previous chapters of this book, we learned how to manage requirements in order to provide a successful software delivery. In this, the final chapter, we will examine how our knowledge can be applied to a real-life use case. Camford University is obviously not real, but the nature of the requirements, interactions, and events described herein are all based on actual cases that I've encountered in my career in the course of various projects. In particular, we will learn about the following:

• Understanding the Camford conundrum
• Eliciting requirements
• Analyzing requirements
• Planning the way forward

This chapter intends to give some context to all the knowledge imparted in this book. You will get a taste of how to apply all the requirement elicitation and specification methods you've learned in this book to a new project. You will also learn how to conduct two important project milestones: the first two client-side meetings.

Understanding the Camford conundrum

Our fictional Camford University is one of the oldest and most reputable universities in the country. As a worldwide center of excellence, they are renowned for their high-quality teaching and innovative research. They publish hundreds of academic papers each year, via their publishing department, Camford Press. They have been publishing ground-breaking papers for centuries, which is where the conundrum lies. Their methods of publishing haven't changed much in the last few decades, which is now causing them a problem as they find it difficult to cope with the increasing supply of papers by an ever-expanding university. Although Camford Press has unparalleled knowledge and skills in the academic peer review and publishing processes, they are not really up to speed with modern technologies and they do not fully comprehend how to leverage such technologies to their benefit. They did upgrade their process to an email-based system a few years back, but they are now looking to move into the 21st century, technologically speaking.

This is why Camford Press has now turned to our organization with an overarching remit:

To automate and improve our peer review process

During our initial communications, they highlighted the main areas they want to address:

• Reduce the time to check whether submitted papers adhere to the University's publishing guidelines. They currently have to do a visual check of each submitted paper, which takes a lot of time and effort.
• Reduce the time it takes to provide feedback to authors. This is currently done by exchanging emails with attached documents.
• Make it easier to find and notify paper reviewers. Right now, they have a written list of reviewers, whom they contact by letter, telephone, or email in order to ask them if they can peer review a paper.
• Create a secure way to transfer and review academic papers. The reliance on email has caused some papers to be sent to the wrong recipients, by accident, and even had some emails intercepted by man-in-the-middle attacks. This resulted in the leakage of confidential and commercially sensitive information, which has caused a great deal of embarrassment to the University.

This is the outline of Camford Press's requirements. We have arranged a meeting with the major stakeholders in order to get more details and increase our understanding of what exactly they need. So, let's attend our first meeting and meet our stakeholders.

Eliciting requirements

At our first meeting with our client stakeholders, our objectives are fairly simple:

1. Get to know the stakeholders and their role in the process we are implementing
2. Obtain a basic understanding of the stakeholders' expectations
3. Understand the stakeholders' goals and identify which capabilities we need to deliver in order to help them realize their goals

It is important that we keep conversations focused and targeted toward identifying requirement domain entities. It's also important that we validate their goals, so as to avoid any unrealistic or vanity goals that may derail the project.

Leading the initial discussions

When we arrive at the offices of Camford Press, we are introduced to the following people:

• Professor Priya Chakrabarti, the editor-in-chief of Camford Press
• Dr. Elizabeth Braddock, Camford University's IS manager

We are also informed that we should have met Dr. Tom Logan, Camford Press' Managing Editor, but he is currently on an international flight and he will be away for the next 2 weeks.

Following the preparatory small talk and cups of coffee, we get down to business and have a structured conversation with the stakeholders.

The Editor-in-Chief (EiC) interview

Us: So, Professor Chakrabarti, could you please tell us what your role in Camford Press involves?

EiC: I have oversight of the whole review and publication process. It is my responsibility to ensure that everything runs smoothly, issues are addressed, and our operation fits in with the University's policies and goals.

Us: Are you involved hands-on with the review and publishing process?

EiC: The day-to-day activities are handled by Dr. Logan, the Managing Editor. He's the one who approves papers for publication, manages the review process, and collates reviewer feedback. I just review the outputs and give final approval for paper publication. Tom is very busy and unable to handle any further increase in workload. I would like to be more hands-on, but I'm also busy with strategic and administrative work myself. We're hoping your system will reduce Tom's workload so that he's not so stressed all the time.

Us: What are these outputs that you review and how do you review them?

EiC: Every paper is submitted to two peer reviews. Dr. Logan coordinates the feedback and necessary corrections and, once no more corrections are required, he emails me the paper, the reviewer's summary, and his recommendation. I review everything and I then approve or reject his recommendation, which is whether to publish the paper or not.

Us: Do you ever reject Dr Logan's recommendation?

EiC: It's extremely rare. I have confidence in my Managing Editor. Dr. Logan may be a bit eccentric, but he is very thorough in his work.

Us: How do you approve or reject a paper?

EiC: I just reply to the original email.

Us: Is your email digitally signed or encrypted?

EiC: Ermm…no, I suppose.

Us: So how would Dr. Logan know that the email is really from you? It's very easy to spoof emails.

EiC: Well, he assumes it is. Also, when I see him, we will usually mention it.

Us: I see. But Dr. Logan is currently away, so he won't be able to mention it in passing for the next 2 weeks at least.

EiC: Yes, I guess that's true.

Us: What would happen if we don't deliver the new system and you keep working the way you currently do?

EiC: Well for starters, I would have to hire another Managing Editor to ease Dr. Logan's workload. You don't know how hard it is to hire good MEs these days.

Us: Are you at all concerned with emailing potentially sensitive papers back and forth?

EiC: Indeed I am. We had an incident a few years back, where a reviewer emailed a paper with confidential data to the wrong person. Luckily, this was an honest person who notified us immediately and no damage was done. But this is a risk we are taking, if we continue working as we are.

Us: Thank you for your time, Professor Chakrabarti.

The IS Manager (ISM) interview

Us: Dr. Braddock, what is your role within this project?

ISM: As the University's IS manager, I am overseeing all IS system development and deployment. My main concerns are with security, compliance, and integration.

Us: Ok. Let's start with security. What are your security concerns?

ISM: Obviously, attaching sensitive files to email is inherently insecure. Also, I am concerned that some of these files, especially ones that support embedded macros, may be a carrier for viruses and other malicious code.

Us: Don't the editors and reviewers virus-scan the files?

ISM: They are supposed to, but you know how people are. They sometimes forget or are too busy to do so.

Us: OK. What about compliance?

ISM: The University prescribes a strict policy for auditing and reviewing the publication process. Currently, this policy is difficult to implement, as it means following a convoluted trail of emails and attachments. I would like the new system to make it easy to see what happened to a paper from its submission to its publication.

Us: Understood. And what are your integration concerns?

ISM: All university systems, like the one you will develop for Camford Press, need to be able to play well with Camford University's Information System (CUIS). CUIS provides interfaces for user authentication, resource management, and other things besides.

Us: How do you envisage our system integrating with CUIS?

ISM: Well, if you're going to have user authentication, which I suspect you will have to, then it has to be through CUIS. We don't allow third-party identity services, such as Google or Twitter, to integrate with university systems.

Us: Thank you for your time, Dr. Braddock.

The Managing Editor (ME) email

We try to arrange a chat with Dr. Logan, the ME, but due to the time difference, this proves impossible. We then send him an email, asking him if he could tell us the following:

• What is his role in the review and publication process?
• Which part of this process would he like to see automated by our system?
• How does he hope our system will benefit him in his role?
• What would be the consequences for him as ME if our system was never delivered?

It is not until the following day that we receive a response from Dr. Logan:

Hello. Let me tell you, I can't wait for your system to be delivered. I have hardly time to eat or sleep nowadays. You can't imagine how hard it is to get two reviewers to review a paper within the same time period. I have to keep emailing people again and again. They are either too busy or just can't do the review within our deadlines. It's a nightmare I tell you. And don't get me started on checking each submitted paper just to make sure it adheres to our guidelines (I am attaching a copy of these, BTW). I have to do that every time an author submits a paper. It would be awesome if I didn't have to do that; it takes so much time.

The rest of Dr. Logan's email turns out to be a long rant about traffic conditions where he is, so we can safely ignore that.

So, we have had input from all our client-side stakeholders and now it's time to try and make sense of what we learned.

Analyzing requirements

So far, we have captured requirements by having structured conversations with the EiC and the ISM. We also had an email communication from the ME. Let's now analyze these requirements in order to identify which requirement domain entities we are dealing with. We'll start by reviewing our interviews first. Structured conversations, like the ones we conducted, are the easiest way to identify requirement entities, as the structured conversation technique we have used is geared toward that purpose.

The EiC interview analysis

We first discovered the type of stakeholder we are dealing with. Professor Chakrabarti is a rare type of stakeholder, as she has business goals but is also an actor. When we asked her if she has hands-on involvement, she replied that she does the final review and gives approval. We also extracted her business goals by asking her what the risks are of continuing to use the current process, which are as follows:

• Preventing data and communication leaks. This damages the reputation of the business and can potentially cost money in lawsuits and so on. Preventing this is a very worthwhile goal.
• Avoiding having to hire new staff. Not only does hiring cost time and money, but in this case, hiring a new person may actually be very difficult. This is therefore a valid business goal.

There is also potentially a third goal, a domain goal, which is as follows:

• Simplify the EiC's final review and approval workflow.

As this would save the EiC's time, and therefore save the business money, this is a goal well-aligned with business needs.

We also gleaned some information about the ME's role and realized that the EiC's strategy for realizing her Avoid hiring new staff goal, is to make the ME's work easier and more productive.

After some thought, we come up with the capabilities needed to fulfill the EiC's goals. These are the ways in which the EiC's needs impact our system. The EiC needs to be able to do the following:

• Securely exchange messages and information. This will fulfill the Preventing data and communications leaks goal.
• Use a single point of access for final review and approval. This will stop the email back-and-forth and the downloading and opening of attachments. This will help fulfill the Simplify the EiC's final review and approval workflow goal.

There is also the goal of Avoid hiring new staff, but it seems we need to talk to Dr. Logan in order to derive the relevant capabilities, since this goal can be fulfilled by reducing his workload. So, for now, we create the discovered entities in our requirements model and move on to the next interview.

The ISM interview analysis

We quickly established that the ISM is a non-acting stakeholder as she won't be interacting in any way with our system. By asking about her potential concerns with our system, we quickly discerned her goals, which are as follows:

• Protect University systems from attack or corruption
• Ensure that systems can be comprehensively audited
• Ensure that applications are integrated with the University's IS systems

All of these are valid business goals, as they have obvious financial incentives. Let's see how our system could enable the ISM to achieve these goals. The capabilities we would need to provide would be the following:

• Automatically detect malicious or corrupt file submissions
• Provide an audit trail of every operation within our system
• Make our system users log in using the University's CUIS credentials.

We add these to our requirements model and move on to the next stakeholder we communicated with, Dr Logan, the ME. As we didn't have the chance to have a structured conversation with him, we'll have to do some extra work in order to identify his requirements.

The ME email analysis

First, let's reword the useful part of Dr. Logan's email in a more structured (and somewhat saner) manner:

• Two reviewers must review a paper within a limited time period.
• Reviewers are requested to perform reviews via email.
• Reviewers respond negatively or positively to a request for review.
• Authors submit papers (presumably by email).
• Dr. Logan checks submitted papers for adherence to guidelines.
• Dr. Logan wants to avoid checking submitted papers for adherence to guidelines.
• Dr. Logan wants to optimize the reviewer request and response process.

Now that we have a sanitized version of these requirements, we can apply the D3 technique in order to identify which requirement domain entities these requirements express.

Decomposing the ME's requirements

By applying the decomposition part of the D3 method, as detailed in Chapter 5, Discovering and Analyzing Requirements, in the Techniques for analyzing requirements section, we identify the requirement entities as explained in the subsequent sections.

Identifying actors

The people, or things, that interact with our system are as follows:

• Reviewer: A university academic in a specialized area who reviews papers in that area.
• Author: A graduate student or academic who wants to publish a written paper.
• Managing Editor (ME): The Camford Press staff responsible for daily editing activities.

Identifying capabilities

The impact the ME is having on our system consists of the following capabilities:

• Arranging reviews: The ME will be able to use our system to arrange reviews in a way that is quicker and more straightforward than it is at present.
• Detecting adherence to guidelines: The ME will be able to use our system to check for papers' adherence to guidelines in a more straightforward manner than at present.

Identifying features

The functionality required by the ME comprises the following features:

• Author submits paper
• Reviewer is asked to undertake a review
• Reviewer responds to a request for a review
• Reviewer reviews paper

Now that we have identified a number of requirement domain entities, let's take a look at how our requirements model looks right now:

Fig. 10.1 – Requirements model following the decomposition of requirements

One thing to note is that we have duplicated the Arrange Review capability across both the scope of the reviewer and the ME. This is because this capability will enable both actors to do their job better. It is pretty obvious that in order to enable the ME to arrange reviews, we will need to implement the feature of requesting a review. It is similarly obvious that in order to enable the reviewer to arrange reviews, we will need to implement the feature of requesting a review.

Another thing of note is that we have identified a feature to allow the author to submit a paper. However, we still haven't fathomed out which capability this feature will help deliver. We write an action item to have a conversation with a number of authors. It is now time to refine our model by deriving some more requirements.

Deriving requirements

The purpose of this phase is to fill in any gaps in our requirements model. The only orphaned entity we currently have is the Author submits paper feature. We cannot really proceed with this until we understand what the author's expectations are. Luckily, Prof. Chakrabarti has kindly arranged a telephone chat with two authors who have previously published papers through Camford Press. Using the structured conversation techniques that we applied when chatting to the other stakeholders, we find that the author's main gripe with the current process is how long it takes to receive feedback and how unreliable it is, as sometimes emails don't get sent on time, or contain the wrong attachments and so on. When we ask them what they would like to achieve through the new system, they both reply that they want reliable notifications for their paper's progress status; that is, they want to know when it passes initial checking, when it has been reviewed by one or both reviewers, and when it has had final approval by the EiC.

Based on this, we add two goals for our authors: Reduce paper review time and Receive timely status feedback. We ascertain two capabilities needed to realize these goals: Submit Paper is the first one, as the author can't really reduce the review time unless they put their paper through our system. The other is Receive progress notifications, and this implies the proactive and timely push of paper status notifications to authors, as soon as they happen.

Now that we have a set of capabilities for all our stakeholders, let's identify some features that will help deliver these capabilities.

Discovering requirements

This is where we discover new requirement model entities, based on the entities we've already identified. Let's start with the ME. He needs to be able to arrange paper reviews from within our system and he would like the arranging of reviews to be easier and quicker than it currently is. The question is: what can the system offer in order to provide this capability in a way that helps achieve that goal? Lisa, our solutions architect, has an idea:

Instead of chasing the reviewers to see when they can do a review, why don't we have them register their availability with our system? Then, all that the ME has to do is select a time period and our system will tell him which reviewers are available at that time.

We email this suggestion to Dr. Logan and, within hours, he responds by saying that this is an excellent idea and he would like this very much. We also approach a previous reviewer and we get the same positive response. We then create two new features to reflect this functionality: Reviewer registers their availability and ME searches for available reviewers.

Next, we turn our attention to the Detect adherence to guidelines Capability. After reading the guidelines document that Dr. Logan sent us, we realize that the main checkpoints are that the paper is written in English, that it has an abstract of up to 200 words, and that it contains a conclusions and references section. Tim, one of our developers, informs us that it is technologically feasible to scan a document's content, detect its language, check the presence and length of an abstract, and verify that certain sections exist. With that in mind, we create a new Auto-scan paper feature. Thinking a bit more about this feature, we come to a realization: this is a composite feature, that is, a feature composed of smaller, simpler sub-features, as described in Chapter 4, Crafting Features Using Principles and Patterns, in the Discerning feature patterns section. We replace this feature with four distinct, more narrowly-scoped features:

• Scan and parse paper content
• Check paper language
• Check paper abstract
• Check presence of mandatory sections

Finally, we apply some identifiers to our entities, as explained in Chapter 6, Organizing Requirements, in the Assuring traceability with entity identifiers section. Our requirements model now looks like this:

Fig. 10.2 – Requirements model following requirement derivation and discovery

Important tip

Many of the Non-Functional Requirements captured in our requirements model can be interpolated into other features. For instance, we could capture the behavior needed for the Detect Malicious Submissions capability by interpolating some steps to automatically scan the submitted files into our Author submits paper feature.

This is the same model we produced back in the Decomposition section, but it's now expanded and gaps between entities have been filled in. Our model is now much more comprehensive. We have a number of features that we can start fleshing out with scenarios. We also have a number of capabilities that don't have any features defined just yet. That's fine. Requirement analysis is an iterative and incremental process. Our model will keep changing quite frequently at first, but less frequently as our understanding increases. We are now ready for our second meeting with the stakeholders.

Planning the way forward

The second meeting with the stakeholders is arguably more important than the first. This is where, after having done our initial analysis, we present our requirements model and seek stakeholders' feedback and approval. This is also the meeting that kick-starts system development. We should now have enough features to have created a small, but perfectly-formed, system backlog (a list of all the features on our requirements model). Our objectives for the second meeting are as follows:

1. Explain the requirements model and get it approved by the stakeholders.
2. Present a first draft of our specification document, as detailed in Chapter 6, Organizing Requirements, in the Creating a specification document section.
3. Identify and discuss any areas of concern or ambiguity, if any.
4. Present and discuss potential risks, if any.
5. Identify a point of contact from our client-side stakeholders. We need one person to represent our client-side stakeholders so as to avoid ambiguity and noise.
6. Explain our analysis methodology and set up a schedule of regular review and discussion meetings. Ideally, we should be having bi-weekly meetings with the client-side stakeholders where we review the model, ascertain its relevance, and make any necessary modifications.
7. Explain our development life cycle, be that Scrum, Kanban, or something else, and ensure that stakeholders know when to expect software releases and when they need to review delivered features.
8. Review the backlog and prioritize features for development.

Regarding that last item, we ask Professor Chakrabarti which capabilities we should focus on first. She selects the following, as the most important and the least likely to change:

• Single sign-on
• Paper submission
• Guideline checks

We can now create our task board in preparation for development, and it looks like this:

Fig 10.3 – Task board for the Camford Press system

Features related to the highest priority capabilities are near the top of our system backlog.Before starting development, our team will have a planning meeting where we will discuss which of these features to start working on first. We will define these features with detailed scenarios, as described in Chapter 3, Writing Fantastic Features with Gherkin Language, and then we will drag them to the To Do column, where these features will be constantly reviewed by our client-side point of contact in order to ensure that we capture the correct system behavior.

We can now begin our implementation, that is, software development. We may be using Scrum, Kanban (refer to Chapter 7, Feature-First Development), or some other agile framework or method to manage our implementation. Embarking on software development does not mean that our requirement management responsibilities are finished. We will be reviewing our requirements model on a regular basis with the stakeholders and we will be changing, creating, and removing domain entities as the project develops. We will also be constantly working with the stakeholders to select features from our backlog, describe them so that they are fully-formed, and move them to our To-Do list when we are ready to start implementing them. Luckily, the previous chapters in this book detail exactly how to do all the above, so we are well equipped to handle our project as it iteratively and incrementally evolves from some vague needs and wishes to a fully functioning system that works as intended. We are well on our way to making our stakeholders' requirements a reality!

Summary

In this chapter, we put our previous learning into the context of starting a real project. Knowing all the techniques, methods, and processes needed to manage requirements and create specifications is very important, but there are other, less tangible aspects of working on a software project that can make a difference. The first two meetings with our client's stakeholders are critical. The first meeting (I call it first contact) is where we establish communication channels and start managing expectations. This is where we start getting a real feel for what our clients expect and desire from our system. After our first meeting, we should be working to produce the outline of a requirements model, which we will open up for feedback to all our stakeholders.

Having our requirements model and specification scrutinized regularly builds trust and confidence between us and the stakeholders. This is why that second client meeting is so important, because it establishes all these steps that foster transparency and communication early enough in the project.

The other thing that this chapter aims to emphasize is the importance of avoiding the waterfall trap. Just like agile software development, agile requirement elicitation, analysis, and modelling is something that happens iteratively and incrementally. Trying to extract every single detail and get a complete picture at the beginning of a project is futile. Many of these fine details can only be derived when both we and our client have a better understanding of what our system will do and how it will do it. Things will be changing often, but being agile means being able to manage change. This is why, in our first project meeting, we don't even try to nail down every detail, just get a high-level overview. We can then analyze requirements in our own time and attend our second meeting with a requirements model that will serve as the starting point of a continuous conversation between us and the stakeholders. Our understanding of the requirements and the requirements model evolve in parallel, one leading the other.

So, we have reached the end of the chapter and of this book. I hope you enjoyed reading it and that the information contained herein will help you deliver successful software systems, with minimum risk and maximum efficiency, just as it has helped me do over the years. Cheers to successful systems and happy clients!