Archive for June, 2016

Non-functional Requirements – Extensibility

Posted on: June 29th, 2016 by admin No Comments

Software Structure Defined

Non-functional requirements such as software extensibility can be very difficult to document as we likely do not know all of the future features or growth we can anticipate for the product as it matures.  Poorly managed, the code may descend into what is sometimes referred to as spaghetti code.  Instead of the document focusing solely upon the features, we can put some requirements for the structure in place before the coding even begins.  A way to do this is through the use of a software design description document.  This document may be especially important the first time working with the vendor or if there are some questions about the maturity level of the software department.  It may not be necessary to create a software design description document for every project.  An organization of a sufficient maturity level may not require such an artifact.  We can glean some understanding of an organization’s capability through reviews of the work processes and activities that are performed during the product development life cycle.

 Don't let your software look like this!


Software Design Description, Requirements, and Structure

The software design description defines the attributes of the software that go beyond the functional and performance expectation.  In this document, the expected structure of the software, software modules, specific interfaces, and data are described.  Defining the structure is important because poor software structure can make the future growth of the product resemble either a well thought out nice addition to our home or some glommed on a disparate piece of work with the associated quality issues.

For example, design entity or specific modules are called out in the software design description standard described in IEEE Standard 1016-1998.  This section of the document places specific expectations upon those creating the software when it comes to software modules.  As the WBS is for projects, the design entity is for software creation.  Specifically, the design entity breaks down the software systematically, identifying the software modules that will be required for the code that will achieve the objective of the product. 

Defined Structure Articulates Expectations

We receive two benefits from this activity. The fist is we will have a better chance of building a well-structured code. If we are the customer and understand what well-structured code is, we articulate our expectation to the supplier in a way that will enable them to meet our expectation.  If we do not have the expertise, we can review this document to learn and question the approach even before we start coding, for example via a review of the document, giving us the chance to identify potential failures in the software structure from the start.  The second benefit comes when we consider extensibility of the software.  We create clean boundary conditions where updating the software at some future date will only require modification or rebuilding few modules instead of creating and weaving in additions around some randomly developed structure.

In addition to identifying the unique software modules, we describe specific attributes of those modules. These specific attributes provide a point at which we can verify the module has been built to expectations.  These are tangible statements that can objectively be tested and certainly be audited or reviewed.

I encourage all who develop software to check out the IEEE Standard 1016-1998.

Non-Functional Requirements

Posted on: June 24th, 2016 by admin No Comments

We have written much on product requirements on the blog.  Requirements are those statements, derived from the project scope, upon which we will build the product.  A clear understanding of these and the circumstances surrounding the use of the product will improve our chances of achieving the desired development objective.

Nonfunctional Requirements

One of the more difficult types of requirements to evoke, write and test can be the non-functional requirements.  Nonfunctional requirements articulate criteria that the system will be evaluated against that are not functionally or use case based.  These are performance based requirements, for example, the capacity of the system.

  • extensibility
  • scalability
  • reliability
  • availability
  • reliability
  • maintainability
  • serviceability

Each of the above requirements may not be associated with a specific feature and are therefore not functional requirements.  These may appear in the specification. I say may appear because unless those who are writing the specification think about these things and how to explicitly document, these may not be included.  Recall that requirements are written in a specific way and reflect tangible and measurable expectations.  For example, consider extensibility. Extensibility is the measure or degree to which software system can be appended or extended.  Finding tangible ways to express this attribute of the software may be difficult, and so too determining ways to test or verify this particular aspect of the software is met can be difficult.

Standards and Nonfunctional Requirements

We may be able to rely upon standards for some of these requirements, for example perhaps, our industry or company has specific serviceability and maintainability expectations identified in standards to which our requirements document may refer.  Sometimes, our team will have to create these attributes of the product using precise wording as these product attributes are also bound by the same qualifiers as the functional attributes.

Things that can help

Writing requirements is not a trivial task and it becomes even less trivial when we work to document these in a way that minimizes omission and possible misinterpretations.  In the case of nonfunctional requirements, the difficulty can be even greater.  Taking time to do this work, doing it iteratively, that is not attempting to write all requirements in one pass, and constant review with the customer and the team will improve the chances of success.

Automation and Paradigm Shift

Posted on: June 21st, 2016 by admin No Comments

The Manufacturing Innovation Network Breakfast went great last week.  Nearly all of the seats were full, and there was a plentiful of discussion afterward.   The discussion was about the role of automation in the not so distant future.  We talked about how automation and drones are now even working in the fields.

Robots came about due to advanced manufacturing techniques and now or very soon, robots will be heavily in the employ of advanced manufacturing.  The consequences of this will likely be the need for fewer people for the manual labor aspects of manufacturing.  However, that does not mean that people are out of the equation. To be successful, those that remain must have a variety of skills. We will discuss more on the people aspect later.  The real discussion point is the notion that we can use our present experience to infer how this will impact our organization.  So far, organizations have automated portions of their manufacturing.  The portion that has been automated allowed for a reduction in human labor for that particular area of the manufacturing, but often the automation moved the bottleneck or throughput constriction downstream.  We would simply move the human resource from the area that has been automated to the downstream or depending portion of the manufacturing process to reduce or eliminate the bottleneck.

When we speak of the level of automation heading our way, we are talking about a more comprehensive set.  That is, we are not referring to portions of the process but the majority if not the entirety of the manufacturing process that can be automated, everything from the moving material to building of the product.  This would mean there are few opportunities to employ the labor as we once did.  Our old paradigm of shifting labor around and in some cases actually increasing the labor to handle these depending tasks due to increased throughput may not apply in the future.  Additionally, just because the automation makes massive volumes possible, that does not mean the factory will produce at maximum volume. The volume produced will be dependent upon the volume demand from the customer.

The next wave of automation will be much more ubiquitous than the last incarnation, building and moving instead of largely moving material.  Some of the rules that applied for partial automation may not apply for whole scale automation of the manufacturing process.  We may be surprised when the automation hits our talent harder than we think due to this previous paradigm thinking.

Structure and Developing Requirements

Posted on: June 9th, 2016 by admin 1 Comment

You do not have to go it alone when it comes to developing requirements. There are many templates and well-defined approaches to help in this regard.  If you are developing a complex system, it is good to break the requirements up, starting at the highest level of abstraction.  We will call that systems specification.  The Institute of Electrical and Electronic Engineers (IEEE) standard 1233, Guide for Developing Systems Requirements Specifications, provides a good starting point for the documentation structure from which we can adapt to our specific needs.  Many organizations work from internal templates which provide the structure of the topics that must be considered when developing the requirements.

 System Development and Requirements

For a sufficiently complex system, we may have a number of specifications involved.  We will choose to work from the greatest level of abstraction of the product, in other words, take a system’s orientation, to develop and define the attributes of the system required to meet the customer or project objective.  This may sound easy, but it is not.  There are likely many incarnations the system can take, and our job is to find the most probable to success.  This often requires some brainstorming solutions, and simulation and modeling to understand the performance possible with the various proposed systems incarnations. Ultimately we will select the concepts and approach that most probably will produce the results we seek and will begin documenting.

The systems level documentation is the tip of the iceberg. However, without a keen understanding at this level of abstraction of the product, we will be ill-prepared to articulate the details of the system.  So, once we know the scope and have developed our systems concept, we will then write detailed requirements specifications for the components of the system.

System Decomposition and Detailed Requirements

An example of specification hierarchy is provided below:

  • Systems specification
    • component 1
      • embedded hardware specification
      • mechanical hardware specification
      • software requirements specification (IEEE 830-1998)
      • software design descriptions (IEEE 1016-1998)
      • functional specification
    • component 2
      • hardware specification
      • functional specification

Why is this important?

So why is any of this important to the project manager?  The requirements point to the customer needs and the objectives of the project. You can think of this as layers or the foundation of our project.  If we build this weakly, then the above layers will be at risk.  The level of rigor or validity of the approach to the requirements will have an impact on the end result. A project manager that knows the organization’s approach to the requirements is able to identify key metrics and take appropriate controlling actions thereby reducing the risk.  Even if the company has no real sanctioned approach, the astute project manager can work with the team to implement specific actions for that specific project that will reduce the risk.  This adaptation in the midst of missing structure or processes will improve the probability of project success.

Good Requirements Attributes

Posted on: June 7th, 2016 by admin No Comments

In keeping with our requirements work, we will start by identifying the attributes of a good requirement.  We start our project off with the requirements, so it stands to reason if we start off poorly or in the wrong direction, we will not make the objective.  This situation will get worse the longer we spend time with poor requirements.

Requirements Attributes

Requirements are not loose; these are tangible statements of the product that are able to be refuted or confirmed.  As we have seen, requirements are part of our project contract closure, but it is also part of our product testing.  To be able to effectively do either of these means we must have requirements that fit the attributes defined below:

  1. Cohesive
  2. Complete
  3. Consistent
  4. Correct
  5. Observable
  6. Feasible
  7. Unambiguous
  8. Required
  9. Verifiable
  10. Traceable

Requirements Failures

Requirements not written in a way that meets the attributes defined above poses some level of risk to the endeavor or the project outcome.  For example, disjointed rather than cohesive requirements will result in the project participants taking conflicting design approaches or solutions to the project.  If the requirements are ambiguous we may see similar failure types as a result too varied interpretation of the requirement possible.  If a requirement is not feasible, we are spending money to do work that will ultimately produce nothing.  Similarly, if a requirement is not correct, we will spend time developing something that will work, but has nothing to do with our objective or our customer needs.

There are many things to consider when writing requirements.  We should not take the approach that all of the requirements must be written in one pass. There are many reasons for that, first and foremost being we do not know everything about the product at the start of the project.  The requirements will unfold or reveal themselves as we work to develop the product. We will discuss that in more detail in a future blog.


Developers, Documentation and Resistance

Posted on: June 5th, 2016 by admin No Comments

Technical documentation serves as a repeatable communications medium. That is, written so that anybody reading with the appropriate competency will come away with the same conclusion.  Not filling this gap or relying upon verbal communications has great limitations. Many of us have likely played that game as children where a group of people line up in a line.  The first person whispers something into your ear and you whisper that into the next person and so on until you get to the end of the line. Seldom does the input verbiage resemble the output.  Additionally, there is no traceability of this verbal exchange.   In this regard, documentation synchronizes the objective and the work of the team.  So we understand what we mean by technical documentation, we provide a few examples:


The skills required for this work may not be exactly the same as that of the developer or person writing software.  Writing software is not about clearly articulating a concept but achieving the feature or feature set of the product.  Clarity is also required for writing code, but it is not the same objective of the documentation.  To that end, some developers may not have the requisite skills or the motivation to sit down and write this type of documentation. For example, when you write code, you can fairly quickly see the fruits of your labors. When you write documentation, it may be some time before you see the results as the document itself may not be considered the fruit of the labor but the product may.


Sometimes it is not the developer with reservations.  Organizations typically want to see results quickly.  I have seen organizations pressure the staff to quickly make progress and one of the first things to go can be this documentation as some believe, erroneously, that documentation adds little value to the process.  Sort of like commenting the code, which under the best circumstances may not be so necessary. The problem is, the best circumstances are not so frequent in occurrence.  Like anything, there is a spectrum or range of scale of documentation, from no documentation, to excessive in which the laws of diminishing returns are in place. That is the increment in the amount of documentation is more costly than to not have that increment of documentation.  This threshold will depend upon the costs, type of product and associated risks.


The way to get better, like so many things, is to study, practice, and collaborate.  For studying, there are standards from IEEE from which the developer can learn about documentation.  The items below provide a few examples of the up front documentation typically associated with software development and is not exhaustive. Though these may be dated and have some superseding document, this can give you a starting point:

  • IEEE Std. 1233-1998 IEEE Guide for Developing Systems Requirements
  • IEEE Std. 830-1998 IEEE Recommended Practice for Software Requirements Specifications
  • IEEE Std. 1016-1998 IEEE Recommended Practice for Software Design Descriptions


These standards provide descriptions of what “good” looks like and are a source from which we can learn and adapt to fit our product and organization’s needs.  Armed with this input, we are then able to set about doing the work, practicing.  This is predicated upon the organization’s recognition of the benefit, though. There must be some line and project management level of support that recognizes this documentation is necessary.  Finally, we move to collaborate.  Documentation is not the sole answer to quality product development. Poor or errant documentation is as bad if not worse than no documentation.  Documentation reviews find problems early and are one of the biggest benefits.  We find problems when we are thinking it through and can be fixed by editing text or graphical models as opposed to up-rooting or cobbling onto the code.


In many organizations, this technical documentation is the kernel from which the customer documentation will grow. Doing so assures us to a greater degree that the product customer documentation matches the actual product features.


Great documentation synchronizes the project and the team from beginning to end.  We are all working from the same script so the chances of us working in technical conflict or at cross-purposes withinthe team are reduced. Additionally, rather than discover this technical conflict during the work, we are in a position to review the documentation before we start working to ensure we are on the same page. Then either the developers modify their approach, or the documentation is modified to better suite the entire scope and objective of the development.  It is much easier to fix documentation in the early phase and then to start development and converge the design work verbally. 

CMMI, Requirements and Institutionalization

Posted on: June 4th, 2016 by admin No Comments

In this series on CMMI (capability maturity model integration) and requirements, we have discussed:

  1. understanding requirements
  2. commitment to the requirements
  3. control changes to requirements
  4. traceability of requirements from detail to scope and back
  5. inconsistencies, the difference between of what is included and what is being done

The processes above work together and amount to managing the requirements.  The degree to which our company consistently does these things in a repeatable way is the degree this approach is institutionalized.  Do we skip these steps when in times of duress?  Experience suggests this happens more often than we care to admit.  If you watch Aircraft Disasters on the Smithsonian Channel (or on Netflix) you will see many of the disasters there are due to skipping process steps that seem innocuous or benign in consequences, only to find out this small alteration in the context of the rest of the system or situation presented is quite disastrous.  An episode that stands out is one that involves a project manager, tires and adhering to a schedule at all costs, not knowing what all costs really meant.  As an aside, the show is a good source of root-cause analysis training, or at least understanding the real complexity of this work.

I bring this up, because I have had some discussions with project managers lately about deleting processes and steps.  Projects can have a variety of situations presented since this is not operations, we do not have a rigid script from which we can work, we may need to adapt. However, that adaptation seemingly frequently includes omission of company defined steps.  To be sure checking our brains at the door and blindly follow the process may not always be the best solution.  However, do we really know the consequences of the deleted steps?  My guess is the project manager from that Aircraft Disasters series that thought the plane must leave on time, and the tires did not need to be more inflated, would not have made that call if he really knew what was at stake by skipping that step.  The same is likely true for the many other situations when that option was selected.


CMMI Inconsistencies: Project Work and Requirements

Posted on: June 2nd, 2016 by admin No Comments

This area of CMMI requirements management has big implications on the project.  Experience suggests project managers can get lost in the minutia of the work, but that is the connection to the project.  The reason we have taken on the project is to produce some result that is defined (or it should be) in the requirements.  Project work that does not support the requirements is work that may not be justified.  I say may not be justified, because there may be some elements in the project work that systematically support the scope.  I would not want to open the possibility for somebody to say, testing the product is not part of the product delivery.  That may be, but testing fulfills the system feedback role, are we delivering presently in a way that would allow us to predict success in the future.  At any rate, the project authorizes work to meet the objective defined in the scope, and supported in detail via requirements.

Requirements and Project Feedback

This specific practice serves as the control feedback loop for the project to monitor and then take subsequent controlling actions rather than blindly believe the plan will deliver to expectations.  With this process area, we will monitor key attributes, product, and project, using this information to guide our depending work and actions.  The CMMI standard describes the activities we take to learn and control.  According to the specific practices, the typical work products are[1]:

  1. documentation of inconsistencies including sources, conditions, and rationale
  2. corrective actions

When the work does not meet requirements.

The interpretation of the measurements will change the project execution and perhaps the project plan should we realize that our plan is incapable of meeting the demand. However, we will use this information to understand what we are doing that we should not be doing, that is, not part of the scope of the project.  There are studies from a variety of groups, The Standish Group 2014 chaos report, for example, listed Clear Statement of Requirements[2], in the top three reasons for project success as the opinion IT executive managers.  Without this clarity, the depending actions to meet the delivery expectation likewise will suffer from this lack of clarity.  Additional actions amount to gold plating or at best misdirection for the project and the product.

Monitor the gap between actions and objectives

To ensure the project results you desire, pay attention to the requirements and the work being performed presumably to meet the scope.  Do not do work that is not part of the project objective, and quickly identify instances where you may go astray, and make the necessary corrections.

[1] Chrissis, M. B., Konrad, M., & Shrum, S. (2003). CMMI: Guidelines for process integration and product improvement. Boston: Addison-Wesley. page 490

[2] (n.d.). Retrieved May 31, 2016, from

Single Sign On provided by vBSSO