Tuesday, September 25, 2018

Determine The Problem Before Writing Requirements

Properly define the problem. (Posted by Jerry Yoakum)


When faced with what they believe is a problem, many engineers rush into offering solutions. I am guilty of this myself - finding solutions and designing systems is an enjoyable activity. However, problems are often elusive. To properly define the problem:
  1. Explore all alternative options for who really has the problem and what the problem really is.
  2. Create several solutions for the perceived problem then explore the range of costs, risks, and time delay associated with each solution. While gathering these details you'll likely discover who really has the problem and why the problem really is.
    • When solving the problem, don't be blinded by the potential excitement of the first solution.
"Procedural changes are always less expensive than system construction."


Reference:
Gause, D., and G. Weinberg, Are Your Lights On?, New York: Dorset House, 1990.

Monday, September 24, 2018

Poor Requirements Yield Poor Cost Estimates

The better defined the requirements, the closer to accurate the cost estimates. (Posted by Jerry Yoakum)


Poor cost estimation can be traced back to these top five causes that all relate to the requirements process:
  1. Frequent requirements changes
  2. Missing requirements
  3. Insufficient communication with users
  4. Poor specification of requirements
  5. Insufficient analysis
Here are some ways to improve your requirements process:
  • Use prototyping to reduce the risk of incorrect requirements.
  • Use configuration management to control change.
  • Plan new requirements for future releases.
  • Use more formal approaches for requirements analysis and specification.


Reference:
Lederer, A. and J. Prasad, "Nine Management Guidelines for Better Cost Estimating," Communications of the ACM, February 1992.

Take Responsibility

No excuses. It is your responsibility to do it right. (Posted by Jerry Yoakum)


In all the [licensed] engineering disciples, when a design fails, the engineers are blamed. Thus, when a bridge collapses, we ask, "What did the engineers do wrong?" When software fails, the engineers are rarely blamed. If they are, the engineers respond with, "The error always existed. My change just exposed it," or "I was just following the pattern," or "My manager made me do it," or " The schedule left insufficient time to do it right." The fact is that the best methods can be utilized in any engineering discipline to produce awful designs. And the most antiquated methods can be utilized in any engineering discipline to produce elegant designs.

There are no excuses. If you are the developer of a system, it is your responsibility to do it right. Take that responsibility. Do it right, or don't do it at all.


Reference:
Hoare, C.A.R., "Software Engineering: A Keynote Address," IEEE 3rd International Conference on Software Engineering, 1978.

Thursday, September 20, 2018

Research-Then-Transfer Doesn't Work

Apply theory and practice at the same time for the best results. (Posted by Jerry Yoakum)


The achievements of software engineering research laboratories have difficulties making it into practice. Some reasons would be:
  1. Software researchers have little experience developing real systems.
  2. Solving a technical problem is easier than making sure it fits in a real system.
  3. Researchers and practitioners have different vocabularies which results in difficult communication.
To best improve the chances of successful transfers, you need to from close ties between research and practice in the beginning. Use the industrial environment as the laboratory in which to germinate ideas. Don't try to formulate an idea then transfer it into industry.


Reference:
Basili, V., and J. Musa, "The Future Engineering of Software: A Management Perspective," IEEE Computer, Sept 1991.

Wednesday, September 19, 2018

Use The Same Name For The Same Concept

Maintain style (Posted by Jerry Yoakum)


Technical documentation must always use the same words to refer to the same concept and the same sentence structure for similar messages. To do otherwise could confuse the reader, causing the reader to spend time trying to determine if there was a technical message in the rewording itself.

For example,
There are three types of special commands. Regular commands come in four varieties.
is not as good as:
There are three types of special commands. There are four types of regular commands.


Reference:
Meyer, B., "On Formalism in Specifications," IEEE Software, January 1985.

Tuesday, September 18, 2018

Every Software Document Needs An Index

Finding information quickly is essential. (Posted by Jerry Yoakum)

An index is a list of all terms and concepts used in the document, together with one or more page numbers where the term or concept is defined, used, or referenced. This is useful for requirements, design, test cases, and maintenance documents. The index is essential to finding information quickly and during maintenance.

Every Document Needs A Glossary

Define all terms in a software document. (Posted by Jerry Yoakum)


It is a frustrating experience to read a document and come across a term that is not familiar. The frustration is short-lived; however, when a glossary is available.

The definitions of all terms should be written in a manner that minimizes the need to use the glossary. One technique is first to explain the term in common, everyday terminology, and then add a second definition that uses other glossary terms. Terms used within definitions that are themselves defined elsewhere should be italicized.

Monday, September 17, 2018

Use Documentation Standards

Do the Needful (Posted by Jerry Yoakum)

If your project requires that a documentation standard be followed, then, of course, follow it. However, never blame a standard for doing a bad job. Standards exist to provide organizational and content guidance.

Innovate! Follow the standard and do it intelligently. That means including what you know needs to be included regardless of what the standard says. It means writing in clear language. It means adding additional levels of organization that makes sense. If you are not required to follow a standard, at least use one as a checklist to verify that you don't have major omissions.


Reference:
IEEE Computer Society, Software Engineering Standards Collection, Washington, D.C.: IEEE Computer Society Press, 1993.

Don't Ignore Technology

Technology is changing so quickly that you must keep up with new developments. (Posted by Jerry Yoakum)

Software engineering technology is evolving rapidly. You cannot afford to sit around without keeping abreast of new developments. Software engineering appears to grow by waves. Each wave brings with it a large collection of fads and buzzwords. Although each wave appears to last just five to seven years, the wave does not simply disappear. Instead each subsequent wave stands upon the best features of all previous waves. (Hopefully "best" means "most effective," but unfortunately it often means "most popular.")

I know of two ways to keep abreast of the technology: reading the right magazines (and books - if very recently published) and talking to the right people. IEEE Software and Communications of the ACM magazines are a good place to learn about what's likely to be useful in the zero-to-five-year timeframe. To learn from talking to people, you must meet the right people. Although talking to folks in your own organization is necessary, it isn't sufficient. Try attending one or two key conferences per year. The presentations are probably not as important as the conversations you have in the hallways.


Reference:
Meyer, B., "On Formalism in Specifications," IEEE Software, January 1985.

Sunday, September 16, 2018

Follow The Lemmings With Care

The majority isn't always right. (Posted by Jerry Yoakum)


"If 50 million people say a foolish thing, it is still a foolish thing."
-- Anatole France

Just because many (perhaps even, most) people are doing something does not make it right for you. It may be right, but you need to carefully assess its applicability to your environment. Some examples are:
In all cases, these offer very positive opportunities for increased quality, decreased cost, or increased user satisfaction. However, the advantages are available only to those organizations in which it makes sense. Although the rewards are significant, their potentials are often oversold and are by no means guaranteed or universal.

When you learn about a "new" technology, don't readily accept the inevitable hype* associated with it. Read carefully. Be realistic with respect to payoffs and risks. Run experiments before making major commitments. But by no means can you afford to ignore "new" technologies (Don't Ignore Technology).


Reference:
Davis, A., "Software Lemmingineering," IEEE Software, September 1993.