On the importance of interface specifications (ICD)

On the importance of interface specifications (doing it and then... following it). Lots of systems fail due to interfaces to external systems. What is an external system? In this context, anything where you'll have to read data from and/or export / write data to.

In some projects/markets these are mandatory deliverables (the designation and the acronym can vary): SIS (Software Interface Specification), ICS (Interface Control Specification), ICD (Interface Control Document). The interface specification can be a document by itself or part of the broader design documentation (a section of it). The advantage of having it extracted is that it is easier to share externally (you'll have to share just that part of the design with external companies and that eases up distribution issues for organizations that restrict distribution).

As per the external interfaces by themselves:
Identify all intervening external systems and specify the needed interfaces thoroughly: specify the data flows, frequency and means of communication, review and accept those documents so that all teams (persons) working for all components of the information system are aligned.


Case study / example (on the importance of interface specifications):

The Mars Climate Orbiter  is one of the many failed Mars missions. It crash landed in Mars in 1999:

• https://en.wikipedia.org/wiki/Mars_Climate_Orbiter

"The primary cause of this discrepancy was that one piece of ground software supplied by Lockheed Martin produced results in a United States customary unit, contrary to its Software Interface Specification (SIS), while a second system, supplied by NASA, expected those results to be in metric units, in accordance with the SIS."

They had a spec, they just didn't read it. Or even worse, they produced contradicting documentation.



PS. The full NASA 1998 report can be found here:

• ftp://ftp.hq.nasa.gov/pub/pao/reports/1999/MCO_report.pdf

Documentation Generation

Your QMS has for sure several rules for documentation generation.

There should be a way of generating unique document IDs for unequivocal document referral, according to the relevant standards. Some standards do require it, and if you're sending deliverables (DLs, like meeting minutes, SRS, SAS, STS, ATS, etc.) to your customer without generating and using doc ids on the DL, probably you're doing something wrong.

On some occasions, some kind of master template / macro will be provided, so that all company templates are easy to update at once (addresses, certifications logos, etc.) and newly generated documents start to use the new company "definitions". For example such an example can be looked here (after saving to your file system, run on Windows Explorer with "New", not "Open", while allowing macros to run).

Some of these templates make use of document fields (see MS Word Document Fields and how to update them - simply do not delete those fields if you need to update those values; F9: Reveals Codes; Shift-F9: Updates field contents, to be sure perform a Close-Open of the document or a Select All + F9 in the body text and in the header/footers).

Example of a master template contents (internal):
https://quality.critical.pt/SitePages/QMS/Master%20Template%20Content%20detail.aspx

The master template can be found here.

Case Study: HUMS Ground Station

An "hypothetical" case study:

The VH-71 was a program for the U.S. presidential helicopter (Marine One).
Imagine that a new generation of Health and Usage Monitoring Systems (HUMS) ground station was to be developed. These HUMS runs on a laptop that stays on ground (thus the name ground station) and after debrief (which is the operation that runs the gathered monitoring systems data - flight data - from the helicopter through a series of algorithms) it will allow for an informed decision (by the maintenance personnel) on whether it is safe to continue to fly it or not for a few more hours.

Would you like to have been part of it? Would you do it using waterfall? What kind of documents would you have included in the technical baseline? Against what standards would it have been built?What level of effort would you have had spent on analysis, implementation, validation and acceptance? What would have been the project duration for it?


About VH-71: It was based on AgustaWestland AW101, formerly EH101 (BTW did you know that the EH101 should have been EHI 01 but a transcription error caught on)?

• Some history on VH-71: https://en.wikipedia.org/wiki/Lockheed_Martin_VH-71_Kestrel
• Here's the helicopter database info with info on all vehicles built (some of them are now flying doing S&R in Canada): http://www.helis.com/database/model/275/
• AgustaWestland is a world giant of the helicopter industry, part of an even bigger company (Finmeccanica): https://en.wikipedia.org/wiki/AgustaWestland
• Related models include EH-101 (https://pt.wikipedia.org/wiki/AgustaWestland_EH101) and AW101 (https://en.wikipedia.org/wiki/AgustaWestland_AW101)
• And now, for something completely different: Some google indexed photos: http://www.google.pt/search?q=vh71a+photos&gws_rd=cr&ei=Xxu9VrWIMsyHaI3ao6gB
• And a model to build your own Marine One: https://www.super-hobby.com/products/VH-71-Marine-ONE-EH-101.html

Links last verified at 2016-04-21.

PS. About the H/C being "like a rock", contrarily to a plane that should... plane (includes a part with the latest Cosmos series presenter, very well known scientist in the US):
https://www.youtube.com/watch?v=BTqu9iMiPIU; and a video with crazy operations and landings being done by H/Cs.

(2016-05-12: Added 2 videos; 2016-05-18: small rephrases; 2017-10-31: added link to HC model)

On software project failures

Software projects fail a lot. And since software is on most modern equipments (read carefully: almost everywhere) most equipments will also fail when running faulty software produced by some of those projects. This is one of the reasons current systems (meaning hardware + software) will also fail a lot.

How much do software projects fail? It's an interesting question and here are some possible "answers":

• The CHAOS report: https://www.projectsmart.co.uk/white-papers/chaos-report.pdf
• The Ambysoft "2013 IT Project Success Rates Survey Results": http://www.ambysoft.com/surveys/success2013.html
• The final presentation of the latter: http://www.ambysoft.com/downloads/surveys/Success2013.pptx

The latter study, published on Dr. Dobbs (which is now inactive BTW), criticizes the CHAOS report. On any case, a good percentage of projects fail and / or are challenged (they do not meet the on-quality, on-budget, on-schedule initial criteria). Just look at the trailer, I mean, just look at the numbers.

Welcome home!

Of course this is not your home. It is mine! So keep off the fence. Except if you want to learn a little bit more on software development.

Some of us reading this have already been through software development projects. Projects are projects: Each one of it is special (if it weren't they would be called "product deployment", "services", or something alike). Bespoke development (i.e. custom-made) has to address a number of... "challenges" of almost any kind. So in reality you are out in the wild. And if you don't take the proper measures you«ll probably get bitten, In time (and with experience) you'll learn what does this means, and most of the times the harder way (more on this also later on).

So why not learn a little bit more on process(es) so that you go along the road a little bit more aware and informed?

If you've reached this final line, you're good: You probably are willing to learn a little bit more. Keep on reading. Here or elsewhere,