Tag Archives: Microsoft Visio

How to Discover Requirements for a Maintenance Project


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.


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.

  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?



Topic 13 – Introduction to Software Design

Why do I need to learn about software design?

What will you do if you are asked to build a house?
You will need to sketch its first and build the house based upon the sketch. Otherwise you may build a house that may collapse in a few weeks or cannot be decorated due to errors.

The situation is similar when you create software. You need to plan how you will build it first by deciding how many components and objects will be used for constructing to solve at least a core problem, what are their responsibility, how they work together, how data will be organized, how data will be flowed within these components, how users will interact with your application, how these components will be deployed.

Software design knowledge will guide you how to do these tasks.

What can I do after finishing learning software design?

You will know how to create a design for an application including static and dynamic structure, data organization, business processing workflows.

Is is really useful? I feel that you can write the code right after having requirements and I am able to refactor my code when needed.

That’s great if you can do it like that. You only need to learn about software design when

(i) you do not know how to write code for a feature or

(ii) you cannot refactor your code because only a small change breaks the whole application or

(iii) you need to write a software system together with 20 other developers and you do NOT know where to begin and how you will integrate results of all the developers into one solution or

(iv) you have a software system that could  serve 20 users simultaneously very well but it stops responding when serving 2,000 users simultaneously and you do not know how to fix it.

Alright! What should I do now?

Software design requires a lot of reading. Each application type (enterprise systems, games, intelligent systems) require specific design knowledge. In this topic, we only focus on basic elements of software design.

In order to get familiar with software design please read
– this Grady Booch et al. (2005). The Unified Modeling Language User Guide. Addison Wesley Professional book, and
– this Craig Larman (2004). Applying UML And Patterns. 3rd Edition. Prentice Hall  book, and
– this Robert C. Martin (2003). Agile Software Development – Principles, Patterns, and Practices. Pearson book in in parallel.

After that please read this Erich Gamma et al (1994). Design Patterns Elements Of Reusable Object Oriented Software. Addison-Wesley Professional book.
Please focus on the Motivation section of each pattern first. You can skip a pattern if the problem presented in the Motivation section is not relevant to your situation or does not interest you.

After that please read
– this Frank Buschmann et al. (1996). Pattern-Oriented Software Architecture: A System Of Patterns. John Wiley & Sons Ltd book, and
– this Deepak Alur, Dan Malks and John Crupi (2003). Core J2EE Patterns: Best Practices And Design Strategies. Prentice Hall PTR book, and
– this Martin Fowler et al. (2002). Patterns Of Enterprise Application Architecture. Addison Wesley book.

After that please read
– this Meilir Page-Jones (1988). The Practical Guide to Structured Systems Design. Pearson Education book, and
– this Bertrand Meyer (1997). Object-Oriented Software Construction. Prentice Hall book, and
– this Grady Booch et al. (2007). Object-Oriented Analysis and Design with Applications. Pearson book, and
– this David Budgen (2003). Software Design. Pearson book and this David Budgen (2020). Software Design. CRC Press book
to learn how to design software systematically.

After that please read this Robert C. Martin (2017). Clean Architecture: A Craftsman’s Guide to Software Structure and Design. Pearson Education book to learn how to create a real world architecture for an enterprise system.

After that please read
– this Len Bass, Paul Clements and Rick Kazman (2021). Software Architecture in Practice. Addison-Wesley book to review software architecture aspects, and
– this Paul Clements et al. (2010). Documenting Software Architectures: Views and Beyond. Pearson book to learn how to document an architecture so that it can be used for communicated, built and maintained, and
– this Humberto Cervantes and Rick Kazman (2016). Designing Software Architectures: A Practical Approach. Addison-Wesley Professional book to learn how to create an architecture systematically, and
– this Nick Rozanski and Eoin Woods (2012). Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives. Addison-Wesley Professional book to learn how to apply theory to create an architecture systematically in real world.

Terminology Review:

  • Software Design.
  • Design Inputs and Outputs.
  • Design Notations.
  • User Interface Design.
  • Database Design.
  • Data Structure Design.
  • Algorithm Design.
  • Object-Oriented Design.
  • Architectures.
  • Architecture Design.
  • Architectural Styles.
  • Architectural Patterns.
  • Design Patterns.
  • Modeling vs. Designing.
  • Analysis Models vs. Design Models.
  • Design Phases.
  • Design Timing.
  • Design Methods.
  • “Good” Design: Modularity, Information Hiding, Data Encapsulation, Low Coupling, High Cohesion.
  • UML.
  • Use Case Diagrams.
  • Class Diagrams.
  • System Sequence Diagrams.
  • Sequence Diagrams.
  • Communication Diagrams.
  • Activity Diagrams.
  • State Diagrams.
  • Static Structure.
  • Dynamic Structure.
  • Design Principles.
  • SOLID Principles.
  • Cohesion.
  • Coupling.
  • Design Patterns.
  • Software Architecture.
  • Architecture Qualities.
  • Package Diagrams.
  • Component Diagrams.
  • Deployment Diagrams.
  • Architectural View.
  • Architectural Viewpoint.
  • Architecture Patterns.
  • Enterprise Patterns.
  • Row Data Gateway.
  • Active Record.
  • Data Mapper.
  • Table Data Gateway.
  • Table Module.
  • Transaction Script.
  • Domain Models.
  • Structured Design.

After finishing learning this topic please click Topic 14 – Software Project Management to continue.