Category Archives: Software Requirements

How to Discover Requirements for a Maintenance Project

Problem:

You are responsible for capturing and analyzing requirements for a project to enhance a legacy system however misunderstandings happen too frequently among your team members.

Context:

A maintenance project is very different to a greenfield project. The key difference is that a business analysist who is responsible for discovering requirements must be not only domain expert but also be able to communicate with technical experts very well. In other words, the business analysist must both be familiar with the legacy system workflows and have adequate technical background.

Suggestion:
  1. Collect existing artifacts, including software products, user guide, administrative guide, installation guide, deployment schema, design specification.
  2. Build a glossary and reference sources.
  3. Get initial agreement about terminologies (terms).
  4. List all system roles.
  5. Walk through the existing user interfaces to determine existing roles and related core use cases.
  6. Collect business problems or needs.
  7. Distill navigation flow and user interfaces related to customer’s problems or needs. Try to find out the exact screens in the existing system related to customer’s problems or needs.
  8. Clarify terminologies. Ask for example values, files, tools for doing something related to unclear or ambiguous terms.
  9. Identify correct problems by asking for demonstration of the issues or limitations of the current system, step-by-step illustrated examples with actual existing values, drawing sketches for guessed needs using a pencil or a tool.
  10. Identify correct needs by asking for user guide, video demonstration of a feature, 3rd party installation files and custom scripts if available, example input data and output reports.
  11. Document business needs by creating use cases with mockups. There might be a need of review of the existing source code and database to indentify initial draft technical solutions when creating these use cases to ensure that they are feasible.
  12. Identify affected features by revising the use cases with additional steps, mockups, data inputs/outputs, descriptions. There might be a need of review of the existing source code and database to indentify initial draft technical solutions when identifying the affected features.
  13. Identify affected roles by revising the use cases with additional or new business rules for all related roles.
  14. Some enhancemens related to technical aspects might require collecting existing technical artifacts. These artifacts might inlcude current database or data schemas, and current software products and source code if possible.
  15. Install tools related to existing source code, then build and run existing source code and database if they are available.
  16. Collect technical problems or needs by listing current technology issues using notes or diagrams.
  17. Analyze techincal needs. These might be data integrity issue (missing or duplicated fields? missing or duplicated rows?) or performance issue (too many rows to handle by current software?).
  18. Finally document technical needs by creating an existing architecture and a proposed future architecture. There is surely a need of review of the existing source code and database to indentify initial draft technical solutions when creating existing architecture and a proposed future architecture.
Things that have to be discovered and confirmed:
  1. Legacy systems: Examples might be access to legacy systems, captured UI screenshots of each sub-systems, parts of database schemas, example data, example legacy source code, legacy codebase.
  2. Problems: Examples might be lack of documentation and expertise, non-scalable architecture, high cost development for new features, unfriendly UI/UX, performance issue.
  3. Goals: Examples might be migration of legacy system to event-driven, cloud based microservice architecture with modern UI/UX.
  4. Budget: Used to select appropriate technologies. Some cloud services, e.g. Salesforce Platform or AWS relational databases, might be very expensive.
  5. Initial text or diagrams: Ask for clarifications of ambiguous terms or components. Does initial proposed solution just need to be general? Should proposed architecture need to be adapted to specific problems, needs, legacy codebase, existing data, and budget?

 

 

How to Discover Requirements

Problem:

You want to quickly capture and analyze requirements for a project developed using Scrum or Kanban method however misunderstandings happen too frequently among your team members.

Suggestion:
  1. Define and get agreement about terminologies (terms).
  2. Decompose a user story into end-to-end workflow with screenshots or mock-ups.
  3. Define test scenarios for a user story.
  4. Use a tool such as Confluence pages for documenting and clarifying user story.
  5. If the problem still persists then try elaborating a user story to a use case, and/or a flow chart, and/or a domain model, and/or mind map, and/or a sequence diagram.
  6. If possible always use face-to-face meetings for communication.

How to Quickly Capture and Analyze Requirements for Building a Prototype or Proof of Concept?

Motivation:

You need to quickly capture and analyze requirements for building a prototype or proof of concept for an enterprise system.

Suggestion:
  1. Capture any artifacts related to a business need. They may be some emails, presentation slides, a proposal document, a legacy system, some similar systems, a feature list or an initial requirement specification.
  2. Define terminologies (terms), build a background and context around the terminologies, expand the terminologies into business roles, business workflows, business components, business entities (objects), and business artifacts as much as possible.
  3. Identify the main stakeholders (roles) who will interact with the system (e.g. Guest, Admin, Developer, User, etc.) and their corresponding business problems or needs (i.e. their motivation of using the software system), and their current business workflows. Create as many scenarios (real world or domain business workflows) as possible. Create a domain model (a model of real world or domain entities, their properties and their relationships) if necessary.
  4. If there is an existing or similar system then identify the core components that each stakeholder will interact with (e.g. Accounts, Profiles, Reporting, APIs, Lessons, Videos, etc.) and their corresponding purposes.
  5. Identify the main tasks that each stakeholder will perform (e.g. Register an Account, Log in System, Create/Edit Profile, Create a Bucket, Generate an API Key, Create/Edit/Delete a Lesson, Create/Edit/Delete a Video, View Bandwidth, etc.).
  6. Identify the inputs and outputs and create mock-ups (sketches) or capture similar screens for each task. The quickest way to create a mock-up is to find similar existing screens in your system or external systems, and modify them. You can also search for templates of similar features in the Internet, and modify them. You can also brainstorm a  new one if you are good at creativity and imagining.
  7. Build or draw a prototype demonstrating 2 or 3 critical end-to-end workflows (An end-to-end workflow is a sequence of tasks that solves a real world problem completely). Contrast a current business workflows with the end-to-end workflows demonstrated by the prototype. The quickest way to create a prototype is to find similar existing workflow of of your system or external systems, and modify them. You can also repurpose a business workflow for a prototype. You can also brainstorm a  new one if you are good at creativity and imagining.
  8. Implement a proof of concept related to the 2 or 3 critical end-to-end workflows.
  9. For a complicated system, you may need to implement a proof of concept, build a prototype, and create a work break down structure or product backlog in parallel to ensure that the requirements are technologically and economically feasible.

 

 

Software Requirements Lessons Learned

Lessons learned 1: Emerging requirements.

Problem: Requirements do not exist. They are emerging and often become incorrect and therefore constant change of requirements happens.

Context: Our goal is to ensure project’ success and client’s satisfaction. In order to achieve this goal our delivered solution must solve our client’s problems and satisfy our client’s needs.

Unfortunately many clients do not know exactly what they want because they want to try a new business process or would like to enhance their current daily business workflow but the new process or workflow has not been defined yet. They would like us to build something for them to try, then if it does not work in real world then they will switch to something else.

The issue becomes even worse when they do not have time to review our prototype and await a quite complete solution.

Sometimes they consider our prototype a complete solution and want us to revise it around their constant changes for production although the architecture limits of the prototype make it very time consuming for such revision or even prevent us from doing such revision. These limits exist because we only build the prototype for the envisioned requirements, not for the endless changes.

Solution:

  • Analysis and communication are critical to ensure that our deliverables match with client’s needs. It does not matter whether we use RUP or Agile process for development. It does not matter whether we use UML, or boxes and lines, or text, or coded prototypes or paper and pen for describing the problems that need to be solved. Our client and analyst must review, refine and confirm problem specification regularly.
  • Otherwise formal requirements should be modeled, reviewed and approved before design phase begins to ensure that our project will deliver solution to the right problems.
Lessons learned 2: Vague requirements.

Problem: Requirements are described vaguely and therefore are implemented incorrectly and many detailed elements are missing.

Context: Our clients just gave us what they have. There could be a video demo of their existing legacy systems, a list of what they wanted, some screenshots captured from other similar systems, a long conversation in an email thread, some phone calls. We just built a solution based on these artifacts and it turned out that our clients had wanted something completely different or many details were missing and not implemented by us.

Solution:

  • Our responsibility is to clarify our client’s problems and needs. Again analysis is an important tool to clarify our client’s problems and needs. Draft requirements can be described in any form, including phone calls, emails, screenshots, video demo, feature list. However all of them should then be refined properly using domain models, workflows, story map, prototypes, use cases, and user interfaces for client to review regularly.
  • Specification by example could help eliminate many unclear aspects when communicating with our client.
  • For requirements of maintenance project, exisiting user interfaces and database schema review are essential for identifying what our client really needs.
  • Sometimes we are stuck at analysis, especially when we analyze integration or enhancement needs that have not existed yet and require creativity. In this case a dirty prototype shoudl be created or proof of concept should be created or small technical exercises  shoudl be done so that we can have inputs for inspiring ideas for analysis.
Lessons learned 3: Requirements dispute.

Problem: Requirements are described only at business level, and therefore many detailed elements are not implemented in the system. However customer does not have time to review the implemented system. When the project is in transition phase it turns out that most of the implemented requirements are non-compliant.

Context: In order to reduce development time and cost many teams just take business requirements and implement them. They may create a work break down structure or a detailed task list for completing these business requirements. However these tasks just describe HOW a business requirement is implemented, NOT WHAT it should be. It means that both USER functional and non-function requirements of a BUSINESS requirement are not analyzed. The situation become bad when it costs too much for a customer to review an implemented business requirement regularly, so the customer just let the teams finish their work. When the project is in the transition phase it turns out that many details of user requirements are not implemented.

Solution:

  • Critical business requirements must be refined into appropriate user stories or use cases.
  • Non-function requirements must be incorporated as notes into each story or use case.
  • Adequate UI sketches (mock-ups) or prototypes or captured screens should be created.
  • Test cases should be created and agreed to validate requirements.
  • A single repository for all requirements should be used for change management and traceability.
  • Architecture and/or proof of concept should be created to discover integration limits of specific requirements.
  • User manual should be created for each business requirement.
  • More importantly, frequent requirements and system validation should be done by a customer if possible to improve the understanding about requirements and prevent communication gaps, especially when an Agile development method is selected to reduce the time and cost. Customer’s assessment must be done regularly (at least weekly, preferred daily if an Agile method is selected), not just once when the project is about to be closed.
Lessons learned 4: Underestimated requirements.

Problem: A requirement is described using one-line description. It may be clear enough for implementation but your team has not built a similar one. Example: Porting a reporting system from R to SQL Server Reporting Services. In the end, it turns out that the effort to implement the requirements is too big due to new programming language learning or the new technology is not suitable for implementing the requirement.

Context: In order to reduce development time and cost many teams just take business requirements and create a rough estimate. The problem is that sometimes there is a lack of experience of a selected technology. Therefore the estimate is incorrect that makes the requirements unable to be implemented within an appropriate budget or using the selected technology.

Solution:

  • Critical business requirements must be refined into appropriate user stories or use cases.
  • Non-function requirements must be incorporated as notes into each story or use case.
  • Adequate UI sketches (mock-ups) or prototypes or captured screens should be created.
  • Test cases should be created and agreed to validate requirements.
  • Proof of concept should be created to discover limits of a selected technology.
Core tools
  • Domain models
  • Business workflows
  • Story maps
  • Requirements analysis
  • Prototypes
  • Use cases
  • User interfaces
  • Specification by example
  • Database schemas

Topic 10 – Software Requirements

Why do I need to learn about software requirements?

Your software can only be successful if it helps people do their work better, faster, with lower cost. In order to achieve this objective, it must fulfill the need of various users. In order to fulfill users’ needs you need to be able to identify their context, problems and needs, then propose software solutions for their issues.

Your software solutions must be built based on its users’ requirements that help them solve their problems. So you need to be able to collect, document, manage and validate their requirements. Software requirements engineering will provide you knowledge for completing these tasks.

Do not waste your time to create software that NO ONE will use. Your software will only become useful if its requirements are correctly engineered.

What can I do after finishing learning software requirements engineering?

You will know how to elicit, document, manage and validate software requirements so that they can be used for creating your software.

Hmm! Is it really useful?

If you still have a doubt about its usefulness then you can delay learning about software requirements until you are tasked to create a software system but you do not know where to begin or what are the inputs for your coding.

Another scenario that may suggest that you should come back to this topic is when you create a software system but unfortunately you find that no one wants to use it.

Alright! What should I do now?

Please read
– this Suzanne Robertson and James Robertson (2012). Mastering the Requirements Process. Addison Wesley Professional book to learn how to develop enterprise software requirements step by step, and
– this Karl Wiegers and Joy Beatty (2013). Software Requirements. Microsoft Press book to learn about techniques for engineering software requirements.

After that please read this Joy Beatty and Anthony Chen (2012). Visual Models for Software Requirements. Microsoft Press book to learn how to use models for representing software requirements.

After that, please read this Alistair Cockburn (2001). Writing Effective Use Cases. Addison-Wesley book to learn how to write use cases effectively.

Then please review this ISO/IEC/IEEE 29148:2011(E) standard so that you could create a quality software requirements specification for projects require high formal specification.

After that please read this Mike Cohn (2004). User Stories Applied: For Agile Software Development. Addison-Wesley Professional book.

After that please read this Jeff Patton and Peter Economy (2014). User Story Mapping. O’Reilly Media book.

After that please read this Dean Leffingwell (2011). Agile Software Requirements. Lean Requirements Practices for Teams, Programs, and the Enterprise. Addison-Wesley Professional book.

After that please read this Project Management Institute (2015). Business Analysis for Practitioners – A Practice Guide. Project Management Institute book.

Terminology Review:

  • Business Requirements.
  • Stakeholders.
  • Sponsors.
  • Customers.
  • Users.
  • Business Analysts.
  • Terminologies, Terms.
  • Problems.
  • Business Goals.
  • Evaluator Pitch.
  • Work Context Diagrams.
  • Executive Summary.
  • User Requirements.
  • Glossary.
  • Business Rules.
  • Business Use Cases.
  • Scenarios, Business Workflows, Business Processes.
  • Storyboards.
  • Process Flows.
  • Activity Diagrams.
  • Swimlane Diagrams.
  • The Brown Cow Model.
  • Business Rules.
  • Domain Models.
  • Business Data.
  • Entity Relationship Diagrams.
  • Data Flow Diagrams.
  • State Models.
  • Features.
  • Project Vision.
  • Software Requirements.
  • Functional Requirements.
  • Use Cases.
  • Non-Functional Requirements.
  • Software Requirements Specification.
  • User Stories.
  • Business Values.
  • Story Map.
  • Product Backlog.
  • User-Interface Prototypes.
  • User Interface Flow Diagrams.
  • ISO/IEC/IEEE 29148:2011(E).

After finishing learning about software requirements please click Topic 11 – Software Construction to continue.