In early July of 1984 Jim Morris, my manager, stopped by my office and suggested I start writing up my project. I thought it odd to start writing so soon; I had not completed my revisions to the computer program. My project focused on my converting the Grade of Service parameter from a constant value to a matrix value. This change would impact an implementation of a Dynamic Non-Hierarchical Routing (DNHR) algorithm applied to a telephone long distance network. While perplexed as to “why” I took Jim’s request to heart and learned another lesson on technical documentation.
My summer job at Bell Labs in 1984 provided me a wonderful opportunity to work with engineers developing a new method to route long distance telephone traffic. In late May I began my job and I had until nearly the end of August to complete my project. My task—modify existing FORTRAN code
for a DNHR algorithm to support having variable Grade of Service (GOS) values instead of the same value for all routes. To make such a change in the code I took a constant—GOS and converted it to a matrix—GOS[x,y]; in which the matrix comprehended some assignment of GOS values according to route location. Besides learning about the algorithm (see previous post), I needed to understand code that someone else wrote. Then I determined the code changes to properly implement the algorithm with this change to a key parameter. While I honestly can’t recall the extent of comments in the code (a very good documentation process), I added my own comments to indicate choices made and the intention of the code. Documentation done! However, Jim wisely thought that comments alone would not be sufficient to help the next engineer.
This lesson of “starting the middle” has stayed with me for 30+ years. I have used it for my own work and my joint work with colleagues. Just like Jim in July I have walked into my summer intern’s cube and instructed them to start writing up their work. Writing equals thinking and engineers are paid to think. Writing sooner means thinking sooner and almost always, in my experience, has resulted in a better end product.
Have a productive day,
Anne Meixner
Dear Reader, What memory or question does this piece spark in you? Do you wait til the last minute to write? Do you document early? Please share your comments or stories below. You too can write for the Engineers’ Daughter- See Contribute for more Information.
Additional Reading
Gerry Ash published a paper in 1985 that was an early description of this technology.
What a great reminder Anne!
I am currently engrossed in the logistics of a field program at the beginning of a project. Because I now work for myself (Staff = me), I can’t delegate details to junior staff anymore. The challenge for me now is to keep my eye on the big picture as well as the details. For me starting from the middle means developing the hypotheses that data will be compared to and clarifying the project goals. So, after my field logistics are no longer on the critical path, I need to change hats and start my report – even if its just a rough outline with notes. Wish me luck!
Hey Deb,
Indeed it’s a great reminder for us all. I learned it early in my career for which I am grateful. Reads like you will be starting even earlier.
I wish you luck in your work and report. Agree is different when you are a team of 1.
One of my most successful projects, we wrote the entire User Manual FIRST for a PLD compiler in the early 90’s (PLDshell). Writing first made us to decide early on all those little details. We had to layout the command lines, options, what devices were supported(and not), how the device features would be accessed, and what screens we wanted to see. It took us about 2 contentious weeks to hammer out the Manual, and only then did we allow ourselves to touch the code. The implementation then had a complete design roadmap and was a slam dunk of another 2-4(?) weeks.
When it came out, only some cosmetic bugs were found. It installed smoothly, and ran perfectly for hundreds of users.
Taught me the value of low-resolution fidelity of user interactions, but most importantly of completing the job all the way from the user experience. I’ve always tried since then to keep the entire end-user views as the main goal. That means shifting perspectives depending on the tasks. For instance, from DevOps, that means making sure Backups are the first things running!
Richard,
Another great example of when writing first makes everything go smoother. Engineers as a profession tend to avoid writing, but it pays off big time.
Sorry for not replying sooner. I will need to check on alerts.