I was working for a startup about four years ago. By necessity and interest I got recruited into technical and product marketing.
I was working hard to distill complicated technical topics regarding our product to a non-technical audience.
I sent a "whitepaper" out to a technical reviewer. If you’re not familiar, a whitepaper is a form of technical writing only non-technical people read. Actual technical work gets called a “paper”. It may or may not be published in a technical journal (e.g. “The Raft paper”)
Anyway, I had hoped for a technical review. I had hoped that I didn't incorrectly represent any of the aspects of our product.
Instead I got the best writing advice I ever received:
This was not a compliment about my writing.
This was a principal engineer at a startup I was working for. I respect their technical chops tremendously. We had worked together on hard problems, and they had explained some difficult concepts to me.
Look at this. You're using this sentence like it's a program and you've got
eight branches. Count them. There are eight. If you got this program from a
junior could you review it?
I've since come to understand it was also not a compliment about my programs.
From some of my first writing in junior high teachers and editors told me "This is a run-on sentence".
They may have even told me "You write run-on sentences". Nobody but this principal engineer had identified why.
If you're a programmer, you will write prose. If you are struggling with getting your ideas across try this: when you write prose, write one idea per sentence. This shift alone will make your prose better. If your prose gets better, your programs will get better.
22nd August 2016
I won't ever give out your email address. I don't publish comments but if you'd like to write to me then you could use this form.
I'm Issac. I live in Oakland. I make things for fun and money. I use electronics and computers and software. I manage teams and projects top to bottom. I've worked as a consultant, software engineer, hardware designer, artist, technology director and team lead. I do occasional fabrication in wood and plastic and metal. I run a boutique interactive agency with my brother Kasey and a roving cast of experts at Kelly Creative Tech. I was the Director of Technology for Nonchalance during the The Latitude Society project. I was the Lead Web Developer and then Technical Marketing Engineer at Nebula, which made an OpenStack Appliance. I've been building things on the web and in person since leaving Ohio State University's Electrical and Computer engineering program in 2007. Lots of other really dorky things happened to me before that, like dropping out of high school to go to university, getting an Eagle Scout award, and getting 6th in a state-wide algebra competition. I have an affinity for hopscotch.