The best teacher I ever had on how to write and how to code was a complete charlatan hack who conned his way into Duke’s English department.
No wait, hear me out: the prof (let’s call him Matt, because I’m not even entirely sure he gave us his real name) was an awful professor in most respects. He didn’t grade anything, I’m dubious he had any teaching credentials in the first place, he often didn’t even bother showing up to class at all, and, while I’m about 95% sure he had some college degree, I’m extremely skeptical it was in English, or that it came from Harvard. Due to his expertise in con artistry, my best guess would be General Studies accompanied by a law degree.
But! Matt could write. And more than that, he made us write. A lot. I wrote well north of 200 pages in that semester just for his class alone. And a funny thing happens when you write that much: you learn how to internalize “write drunk, edit sober” in a way that can be trivially practiced when all you’ve had is coffee and a bagel at 8am and the paper’s due at 12.
The basic process that Matt drilled into me, which I do still use: first, just get stuff down into your text editor of choice, not taking any time to edit whatsoever. It can be crap; that’s fine. If the whole thing is crap, throw the whole thing out and just start over, because you didn’t spend any real time on it anyway.
When it’s at least 50% crap or less, start your structural editing pass. To do that, you begin by writing out a sentence off to the side of what you want your paper to achieve—for example, “convince the team to use automated test environments.” (Or in Matt’s case, “convince the class that me not showing up for class half the time is due to being bedridden by illness, despite the fact that at least two of my students saw me not even fifteen minutes ago eating a bagel in the cafeteria.”) Then, go through paragraph by paragraph, and make sure that each paragraph relates back in some way to that topic. If it doesn’t, just kill the entire thing. If it does, then leave it.
Once you’ve done that per paragraph, go through each paragraph’s individual sentences. The first sentence (or occasionally, the second) should dictate everything in that paragraph. If you find sentences that don’t relate, either kill them, or consider putting them in their own paragraph—provided, of course, that the new paragraph would tie back to the overarching theme.
Next, read the entire paper out loud. “Out loud” is key: writing does have a different cadence than speech, but it’s still ultimately a language, and language is verbal. It can sound highfalutin’, if that’s appropriate for the audience, but it should still sound correct to your ear. It may be hard to resist doing at least some grammar and punctuation tweaks as you do this, but your main focus needs to be on the flow, and on whether you actually made your argument. Flow is easiest: you presumably nuked sentences and whole paragraphs; some of the paragraphs are probably no longer in the right place. You’re in a word processor. Move them. Likewise, you may now realize you need connecting paragraphs, or an extra persuasive point hits you during the read. Add those in.
Persuasiveness is trickier: try to approach what you wrote from the perspective of someone who knowledgeably disagrees passionately with your point. Can you drive a truck through your claims? Do any of your points have superficial counterpoints you didn’t address? There’s a trade-off between addressing every complaint, and refusing to even respond to trivial, obvious problems. Try to handle the big issues preemptively, but it’s okay to ignore obscure ones unless someone actually asks about them.
Finally—and last!—do a real grammar pass. Again, reading out loud is your best bet here: there are “rules” for punctuation, but, when you’re not doing the SAT or submitting something to a teacher who walks around with Strunk and White shoved into their back pocket, follow how you talk, not the rules. You may develop a love for the Oxford comma, or for semicolons, or for short paragraphs, or any of a dozen other things that are “incorrect”. Or, for that matter, you may develop a love for the comma splice, the run-on sentence, the gargantuan oil tanker of a paragraph that simply does not know when to shut up. But…it still needs to sound good, and it needs to be clear.
When you’re all done, you should have a tight document that makes its points clearly and tersely, but completely. It won’t overstay its welcome, but it won’t leave you grasping at straws, either.
One advantage of having a writing class from a bullshit artist is that Matt knew what he was doing. That process works. And it’s still my process.
The fun thing is, this process works for code, too. Too often, coders get stuck trying to think about the One True Way to Solve the Problem, and end up not writing any code until they have figured it out. Since it’s sometimes impossible to “figure it out” by just thinking and staring at a wall, they end up feeling burned out and unable to make any progress.
But you’re in a code editor, and likely one with powerful built-in refactoring tools that are far more capable and helpful than anything that exists for an aspiring writer. You likely can trivially extract functions and classes, rename variables, track callers and callees, and all the other things you’d need to do to refine your idea with just a few clicks and a minimal amount of typing. So, use it: take the exact same approach you’d take with English and just start writing.
Get something that works, no matter how silly and brittle. Don’t think too hard about it: don’t worry about it being DRY, or being as fast as possible, or properly encapsulated, or anything else. Just get something that works. If it’s garbage, throw it out and start over; you barely spent any time on it anyway. Once it’s mostly not garbage, begin a refactoring pass. Make sure that what the code is doing is clear, concise, efficient, and above all, makes sense to read—because you will forget where your head was at in six months when you inevitably have to do some maintenance on this code. That means not slavishly holding to things like DRY; instead, think carefully about whether a little bit of duplication actually helps with flexibility and readability. Sometimes, it really does. Sometimes, it’s very much time to bust out a new class or a higher-order function. Try to approach the decision from the perspective of someone reading the code who needs to fix prod urgently and has no idea how anything works: are they going to be able to get oriented quickly? Are there any pieces you’ve done where you’d be screaming “what the f—?” in that process? Make sure the answers are “yes” and “no,” respectively, to the best of your ability. When you’re done, you should have something that’s clean, efficient, and highly maintainable.
So there you have it: the best writing and coding instructor I had was a charlatan hack with dubious credentials. Sure, he should never have been allowed within ten feet of a classroom, but I’ll give him credit where it’s due: his lessons are some of the few that have actually stuck with me all these years, and I’m grateful I had them.