Embrace The Non-Geek
My first job as a professional software developer was in 1979 with a small (8 people!) consulting company in upstate NJ. They actually had two locations, a storefront “lab” that housed all our development equipment and an office that was a converted church. My office had a stained glass window!
This company did some telecommunications consulting and embedded system development for on large client. It was a Z-80 microprocessor device that extracted call records from large switchboards, converted them to a standard format, and stored them on a disk. Our client’s systems polled these devices a few times a day and used the data to produce one of the first phone traffic reports in the industry.
My boss was a big proponent of designing before coding. Structured Design by Yourdon had just been published. No cowboy coding for this new grad! We wrote a rather large (considering it was a 7.3k assembly language program) specification that outlined everything. We had data flow diagrams, data dictionaries, flow charts, yeah the whole enchilada.
But the best part was the functional description. My boss insisted that it be written in plain English - no acronyms or overly technical terms allowed. If a technical term was unavoidable, it had to be defined right in the text, no “see glossary” in parenthesis.
The problem was how do I determine if the description was “English” enough? Well, as it turned out I had access to a real live Brit in the form of our secretary, Rona. So, I after a offering a bribe of doing of the Post Office runs for the rest of the week, I ask Rona to read the functional description, all six pages of it. When she was done, I sat down and asked her “what does this do?” To my relief, she got 90% of it “spot on” as they say in her homeland. Now Rona was pretty sharp, but she was not technically trained at all. So, I’ll take a bow and accept credit for my clear and concise writing!
But that’s not the really neat part. Though we knew we were going to poll the device several times a day, how would we know how many times to call so that the disk did not get full? Well, the functional description described a prediction routine that based the next calling time on the number of records pulled off the desk on the last poll. It would work but was not really as clean as we would like.
Just before I was going to leave Rona’s desk, she looks at me and asks “About that polling thing, why don’t you lads just have the little box call the big box when the disk is almost full?”
Two embedded programmers, a manager and a mainframe programmer working on this and no one thought of the obvious! Needless to say, the idea was much better and worked great.
The moral here is two-fold:
If you can explain a system in plain English and a non-technical person can understand the concepts based on that explanation, you probably have the system figured out pretty well.
If the non-technical person asks a question, pay attention! You may have missed an obvious flaw or improvement that only someone not involved with the minutia of the development would see.
Needless to say, Rona got a few extra paid days off.