Monday, September 03, 2012

2012-09-02 Monday - Book Review: VIsual Models for Software Requirements

I review for the O'Reilly Blogger Review Program 


Book Review: Visual Models for Software Requirements 

by Joy Beatty, Anthony Chen


I'll start-off by saying that if you have no process or discipline in your organization's approach to documenting and capturing software requirements - there are a lot of good suggestions covered in this book. Also, if your approach to documenting software requirements lacks an appreciation for the business concerns - the Business Objectives modeling discussions in the book may be helpful and/or useful for your software engineering team.  However, if your software requirements management processes are even moderately mature - and if already using Microsoft-centric tools to capture and manage software requirements - you will not find much that is new, novel, or of benefit in this book.

  • An attempt to provide a comprehensive approach with an emphasis on business concerns
  • Coverage of the importance of Business Process modeling
  • Highlights the limitations of UML to capture business level concerns'
  • Focus on Business Objectives modeling
  • Discussion/coverage of Key Performance Indicator Models (KPIM)
  • 'Feature Trees' [although, for any moderately complex effort, the choice of a visual modeling tool for drawing a Feature Tree - that lacks zoom/collapse capability of nodes - is problematic]
  • Inclusion of helpful links to references and additional resources at the end of each chapter.

  • Lack of integrating the Business Objectives modeling concepts with other mature software engineering models (e.g. Zachman Framework,  Open Group TOGAF)
  • Microsoft-centric / bias in promoting tooling
  • Lack of any significant discussion of other possible software requirement tooling for visual modeling (i.e. non-Microsoft-centric tooling)
  • Lack of appreciation / coverage of how to minimize the manual maintenance of traceability across artifacts
  • Promoting a software requirements approach that relies on Sharepoint as a primary mechanism for publication/distribution is an abysmal experience as the size and duration of a project grows.
    • Link-rot: Over time, Sharepoint sites are renamed, restructured, reorganized.  This results in an untenable maintenance effort for most organizations.  Links embedded in MS Word, PowerPoint, Excel, and Visio documents are routinely broken - and identifying where to change all of the link references is also challenging..
    • Painful and labor intensive efforts to automate any generation of cross-references or matrices [when visual models and requirements are stored as MS Office documents across multiple SharePoint sites].

 In choosing this book to review - I was hoping to find some new insights to capturing requirements - via visual models that might eliminate some of the 'pain' that most often is found to exists in the requirements management processes (and tooling) adopted by most large organizationsSince this book is written with a bias toward Microsoft(tm) technologies (e.g. SharePoint) - teams that attempt to adopt the suggested approach will eventually run into the same types of long-term problems and 'pain' that I have observed firsthand on many projects - across several different organizations.

At the end of the day - after having lived with the pain of an absence of integrated tooling for the capture and management of software requirements on too many projects - I must conclude that the authors lack of a integrated vision of tooling for visual software requirements management leads me to suggest avoiding this book for the majority of potential readers.

2012-10-09 Tuesday Update:

Tonight I received a follow-up question in response to my Amazon review for this book:

I found your review of the book "Visual Models for Software Requirements" to be very helpful and intriguing. The negatives you list for the book touch on some items I am looking to find a solution for. I am not a programmer, yet I aspire to use the tools of programmers to manage information in the form of data files, Word documents, graphics, Excel spreadsheets, PDF, text, etc. I was thinking of looking into Sharepoint as a means to keep the information organized, cross-referenced, searchable, and shareable. Then I read your comments about the "absymal experience" that Sharepoint becomes when used as the primary mechanism for publication/distribution. Your description of the broken links embedded in Word, Powerpoint, Excel, etc. is exactly what I want to avoid.
So this brings me to my reason for writing to you. You mentioned that you have lived though the pain of an absence of integrated tooling for the capture and management of software requirements, which seems to imply that you now live relatively pain free. What tools do you use to capture, organize, maintain, and share requirements? I'm thinking what you have learned and are willing to recommend may provide me with ideas for something that may work for me.
Thank you for your time. 

xxxxx xxxxx

Here's my reply:

I'm happy to share with you my thoughts/recommendations - although it isn't a silver bullet. Even if I found the perfect tool - there are still challenges. For example, enabling collaborative editing of content with most visual modeling tools - doesn't scale well across organizational boundaries. In particular, for some industries that are very sensitive to a default security approach of 'nothing-shared' - the willingness of the organization to allow that cross-boundary access to information is often a battle that cannot be won.

Two approaches that I've used in the past:

1) Leveraging a wiki tool (such as wikmedia or TikiWiki)
- Allows easy creation and editing of content - as well as deep linking of the content within a single application container.
- Content can be ported (or archived for a snapshot) by exporting data from the wiki database.
- No expensive application licensing
- Scales well - wiki content is easily searched
- requires organization discipline in how content is arrange and organized
- wiki page links can become orphaned [but most such tools have a feature to easily identify orphaned pages - try answering that same question with an organization containing many Sharepoint repositories - that exist as independent silos]
- wiki's don't have inherent modeling / diagramming capabilities [however, there are options for creating custom plug-ins - so that may be a surmountable challenge - with some investment upfront]
- requires some discipline (and establishment of organization / processes) for how to organize and manage externally generated content (that may be either linked to, or uploaded to a central folder - for reference in wiki pages)

2) Leveraging a modeling tool that supports a centralized repository (such as Sparx Enterprise Architect, or other similar commercial products)

- Supports publishing easily navigated HTML content
- Models (and model elements) are logically connected - so moving an element or package up/down in the hierarchy maintains the physical links to the content
- Supports rich annotation and complex relationship associations
- Supports automated generation of traceability matrices
- Easily supports generation of comprehensive documentation
- Supports establishing traceability for multiple purposes (e.g. testing, requirements, use cases, used-by, uses, etc.)
- supports searching across the entire repository and filtering rules
- supports capturing knowledge in a single repository - across organization roles (business analysts, architects, developers, testers, data modelers, network/infrastructure

- Per-seat (or floating) license costs can be a burden for large organizations
- Content published to HTML format must be round-trip updated/published to update the HTML content.
- diagrams that can be exported (e.g. .png,.jpg, .gif, etc) are not always of an optimal resolution for viewing in slide decks or word documents.
- [typically] requires connection to the repository to update content (although there are processes that can be established to bridge this - for example, leveraging version control for model check-in / check-out)

These are some of the trade-offs that immediately come to mind - and are all preferable to the nightmare of trying to locate information across multiple Sharepoint repositories - and links that may be broken due to sites being restructured, moved, or deleted.

No comments: