4 min read

Best technical writing...evah

The agile manifesto is seriously great writing.
Best technical writing...evah
The agile manifesto
Has any written words had greater impact on tech than the Agile manifesto?

Show Notes

0:05
Hey folks, welcome to The Imposters Club podcast for misfits in tech. I'm your host, Teddy Kim. I had a weird insight the other day that I'd like to share with you. I've reached the point in my career where I do more writing than coding. Who would have known it would be like this? Anyway, the other day, I was struggling with a bit of prose, is it clear? Is it confusing? Who can tell? Writing is a lot like coding, if you stare at the same words for too long, they start to swim around and confuse you. At times like these, I rely on the Hemingway editor to get unstuck. If you haven't heard of Hemingway, you have to check it out.

0:47
Hemingway is an editor that uses the automated readability index to give your writing an overall grade-level score. So if your overall grade-level score is eight, that tells you that an eighth-grader will be able to understand your prose. Since the average American reads at a 10th-grade level, a score of say nine means that your writing will be accessible to a pretty fair portion of the population. Anyway, on this particular piece of writing, I couldn't get the grade level score beneath 11 and that wasn't going to cut it.

1:22
The writing I'm struggling with right now is a department-wide statement of values and principles. This is the type of writing that could potentially shape a team's culture for a very long time and I'm going for maximum impact. So the writing needs to be crystal clear. Well, after spinning my wheels for a bit, I had a crazy idea. Maybe the Hemingway editor is wrong and I'm right. How about that? How can I validate that the app is doing what I think it's doing? So I framed a little test. What if I were to cut and paste the Agile Manifesto into the Hemingway editor? How would that writing stand up? Well, surprise, the Agile Manifesto has a grade-level score of eight, which is very good. And that got me thinking, What if the Agile Manifesto had been written by bad writers? Could the same ideas expressed poorly have the same impact? I don't think so.

2:35
One of the most unique aspects of the manifesto is that it conveys very complex ideas and language that even little kids can understand. The language is aspirational without being flowery, and it tells a compelling story. Okay, so it's not Shakespeare, but the Agile Manifesto is excellent writing by any standard. And let's talk about impact, I honestly can't think of a more impactful event in tech than the Agile Manifesto, like it, love it, or hate it. Maybe Linux or certain chip innovations, you could make a case of maybe the rise of boot camps in tech. We'll see how that plays out. But if you think about the sheer number of products, consultants, companies, books, videos, conventions, tools, the list goes on, so many things have hatched out of the manifesto. It's mind-boggling. Entire ecosystems and economies revolve around agile, or what people call agile.

3:39
Agile is even in play in the Pentagon, so you can make the case that entire countries have felt the impact of their Manifesto. Now, here's something fun to think about. Everyone in tech has heard of Kent Beck, Martin Fowler, Andy hunt, Bob Thomas. They are luminaries in our industry. In the parlance of our times, these and the other signatories of the manifesto are legit ballers. But I challenge anyone to name a single piece of tech or software system that one of the original signatories of the manifesto is responsible for. Okay, a certain type of nerd might know that Kent Beck and Erich Gamma wrote Junit. That's a gimme. But I'm guessing that most of you are probably scratching your heads right now. Other than the Agile Manifesto, what did these guys do? Well, they did a lot.

4:39
The point I'm trying to make is that some of the giants in our industry are best remembered for their writing, not their coding. How far a stretch is it to suggest that these folks became giants in our industry because of their writing and not because of their coding?

5:01
Interesting. Anyway, no more speculation. I want to leave you with something actionable. All you nerds out there. Let me give you some unsolicited advice. Compare the shelf life of your programming language to the shelf life of the English language. In a decade most languages will be anachronisms, so consider your intellectual investment carefully. Nobody's gonna care if you can code in elixir in 2029 but job offers, resumes, and paychecks will still be written in English. In strictly careerist terms, your ability to persuade and inspire will always trump your ability to code, and to persuade, you need to write well.

5:50
If you'd like to improve your writing, and you're looking for someplace to start, give the Hemingway editor a shot. Hemingway can help you with the fundamental correctness of your writing. And for most people, that's a good starting point. Now, if you want to write more artfully, study great writers. Try to figure out the techniques great writers use to persuade, convince and inspire. And that brings me back to the manifesto. I can't resist observing that the first sentence and the last sentence of the manifesto are perfect bookends.

6:26
The first sentence says we are uncovering better ways of developing software. And the last sentence says at regular intervals the team reflects on how to become more effective. The first sentence establishes suspense and the last sentence leaves you with a cliffhanger. How will the story end? The answer is up to you.


I'm hiring software engineers! Check out the jobs page to see my open positions.