Writing Well

A personal journey from reading about database to writing about jazz on a baritone ukulele.

My Path

If you were involved with computers in the 1970s you would be impressed with the name James Martin.  He was big then, but fame is so fleeting, even programmers today don’t know of him.  However, then, he used to get $20,000/day consulting for large companies on software strategies, and was a prolific writer on all things computer.  He supposedly made more money selling text books than any other text book author.

I was the kid good at math and hated English.  This led to a programming career in my 20s, working in aerospace.  When I was around 30 I decided to leave aerospace and work in the commercial sector, for a company selling mainframe database software.  (Late 1970s.)

I didn’t know anything about database technology, so I bought James Martin’s book on database.  A large book.  I was ready for a slog, but instead, it was like reading a best selling novel.  And database knowledge just seemed to osmose into my brain.  I was amazed, how did he do that?

That book got me interested in the challenge of writing about technical things.  I saw a similarity between trying to logically structure software code to solve a problem, and trying to logically structure sentences and paragraphs to explain a topic.  I started to dabble in articles for trade magazines and the like, all about a software niche, Prolog, I was doing as hobby.

40 – time for a midlife crisis, I had abandoned the commercial software companies and had decided to make it on my own. It wasn’t going well.  I was almost out of money and ready to crawl back to the commercial world when my son crashed my car (nobody hurt) with surgically precise damage that got me a check from the insurance company for the total, which I didn’t need to spend on the car, and provided me funds for another month.

Then, and here comes the too coincidental to be a coincidence part, a fellow I’d known back in my aerospace days noticed I was doing some writing, and asked if i wanted to work for James Martin.  Turns out James Martin had spun off a bunch of other writing products and needed writers for them.

So I started doing contract work for the James Martin Report writing in-depth papers on various IBM technologies and ghost writing a magazine column for him.

It was all about the illustrations

He told me that there was a direct correlation between the number of diagrams in a text book and the sales of that book.  But it wasn’t just that he had illustrations, it was that they were how the book was written.

(I’ve always been fascinated by how writer’s creative styles affect their work, like Wodehouse used to make three story lines on pieces of paper tacked around the walls of his cabin and then look for ways to have them intersect, and if you read his books, well yes that’s exactly what happens, and Elmore Leonard coming up with characters and then putting them in situations to see what they do, instead of having a plot, and in his books the characters are memorable but you never remember the plots.  Like that…)

James Martin had a bunch of folding tables in a big room in his large house in Vermont. (He had bought it from Larry Bird’s Celtic teammate, Kevin McHale, who had designed it for a tall person, as James Martin was.) He drew diagrams, charts, pictures on pieces of paper and laid them out and organized them on these tables. If anything wasn’t clear, he’d add more pictures.

(Hmmm, I bet the large spread out physical work space let him work with the big picture a lot more easily than someone sitting in front of a computer screen, double hmmm, I bet that explains Wodehouse’s ability as well…)

(Triple hmmm, total digression, these are thoughts just popping into my head, not part of what I was trying to say, but Wodehouse has been called the best writer of English language fiction, and James Martin has been called the best writer (he’s English as well) of English language textbooks, and both used large scale spaces to lay out their works before setting pen to paper.)

Then Lillian, his red-haired girl friend who used to be married to someone who worked for the Shah of Iran and was kicked out in the revolution, would computerize his drawings, and then he would write the words that glued it all together.

I went back and looked at some of his books.  There was never a page without some chart or diagram on it.

When he told us how he wanted the articles in the report written, he had a series of basic diagrams that he wanted us to fill in for the particular technology we were covering.  These diagrams had differing relationships of visual elements that would illustrate the layers and connections between elements of a technology.

And the structure

He also had an overview architecture that we followed that solved the problem of how to talk about interconnected bits of technology and drill down on one bit without fully explaining the other.  It added two steps to the classic, tell them what you’re going to tell them, tell them, tell them what you told them structure.

The technology document sections were: 1- abstract, a paragraph, 2- executive overview, a one page discussion of the technology, 3- overview, three-five pages describing all the components of the system and how they related, and only then, 4- a 30-50 page detailed dive into the technology, including examples of use worked out, and 5- a summary.

That detailed overview made it possible to write the deeper details referencing bits of the technology that had not yet been covered in depth.  Did that make sense?  So if A is related to B, then because the relationship is laid out in the beginning, the in-depth analysis of A can refer to B before B has been described in detail.  And of course there were diagrams that had A and B visually related.

My Ukulele Book

And, so now around 70, retired mostly from software, and trying to learn about music, I discovered the Baritone Ukulele and started playing with chords, and decided to write the book.  As you can see, it’s lots and lots of diagrams that tell the story and mostly they came first.  But yes, I care about the words too and did go over them many times. At a parent-teacher function my son’s English teacher noted that there’s no such thing as good writing, only good re-writing.