Stop Writing Documents Nobody Reads

I learned this lesson the hard way.

I learned this lesson the hard way.

It was 2017 and we had acquired another business, and as CTO I was responsible for planning the integration. I poured all my knowledge into a dissertation-length proposal, referencing nuanced management frameworks, detailed architecture proposals and suggested operating models. In the review meeting, instead of joint appreciation of just how clever the proposal was, the C-suite met me with blank stares — they hadn’t even read past the first page.

It was a wake-up call.

The higher you climb, the more your success depends on effective communication and increasingly, written communication (thanks Jeff Bezos 9_9).

Communicating your ideas and concepts to inspire action is a specific skill. Like many technical leaders, I was still writing to pass exams rather than to drive change — and it was limiting my career. It wasn’t until I watched Larry McEnerney’s lecture on effective writing that I understood why.

Adapting his insights to business writing, I have developed a 2-step process, which I now use AI to accelerate.

The Problem with Academic-Style Writing

One of McEnery’s key insights is that we learn to write in school, where our teachers are paid to read our work. Their job is to check for the completeness of our understanding. This conditions us to expect our writing to be evaluated rather than truly read. But this explanatory approach isn’t just inappropriate in business — it’s actively harmful.

Your CEO doesn’t need another evening filled with reading your technical exposition. They have not hired you to prove your technical knowledge but to act based on it.

Your engineering team doesn’t want to wade through pages of context they already understand. They need clear direction and compelling reasons to act.

So, if academic writing style is the problem, what’s the solution? It starts with recognising that writing serves 2 distinct purposes: thinking and influencing. By separating these purposes, we can keep the benefits of detailed analysis without subjecting our readers to it.

Step 1: Write to Think

The first phase of technical writing is all about your understanding. Writing isn’t just a way to record pre-existing, fully-formed thoughts and ideas but an active part of the thinking process. It is where we discover and develop what we actually think.

When tackling complex technical concepts, you need space to explore, connect, and validate your understanding. Traditional long-form documentation and structured thinking approaches serve this purpose:

• Create comprehensive descriptions of challenges and rationale

• Document all relevant reference materials

• Link to related concepts you have acquired in your notes system or second brain

• Explore edge cases and technical implications

This initial work is essential. It forces you to understand your ideas, test them and uncover gaps in your reasoning. It’s the foundation of technical clarity — but it’s only half the journey.

Step 2: Writing to Influence

Here’s where most technical writers stumble. We take our exploration and thinking and simply share it, assuming others will invest the same energy in understanding it. They won’t.

I have learned that if you want people to read what you write, and change how they see things, you need to transform your thinking into a format and message tailored to your goal.

The process requires 3 key elements:

1. Know your Audience: Understand their pains, technical depth, and decision-making process because influence comes from addressing real needs, not showcasing knowledge.

2. Craft your Narrative: Frame solutions through the audience’s challenges, in their language, because technical brilliance only creates value when others can see it.

3. Drive Clear Action: Make next steps crystal-clear and define what success looks like because vague recommendations rarely drive change.

The ruthless editing is the hardest part. This transformation from comprehensive explanation to focused influence feels like sacrificing clarity (and killing your darlings) for brevity. It’s a painstaking but essential process.

After struggling with this challenge for years, I started to use AI as an objective editor, helping maintain technical accuracy while reshaping content for maximum impact.

The AI-Enhanced Technical Writing Workflow

The key to leveraging AI in technical writing isn’t to replace your thinking –it’s to accelerate the transformation from understanding to influence. Here’s my process:

• Select a writing framework that is most appropriate for the content, audience and business

• Create a prompt designed for AI to help extract and reshape the content

• Apply the prompt to transform my comprehensive documentation from step 1

Here’s a prompt I use that combines 2 consulting stalwarts frameworks: Barbara Minto’s Pyramid Principle and the SCQA (Situation-Complication-Question-Answer) framework.

You are an expert technical writer tasked with transforming complex technical documentation into a clear, audience-appropriate summary. Follow these steps:

1. First, analyze the audience profile provided and note the key characteristics that should influence the summary's content, complexity, and tone.

2. Use the SQCA framework to structure the initial analysis:
- Situation: Identify the current context and background
- Question: What problem or need does this documentation address?
- Complication: What challenges or complexities are involved?
- Answer: What are the key solutions or recommendations?

3. Then, apply the Pyramid Principle to organize the information:
- Start with the main conclusion/message at the top
- Group related supporting ideas into logical categories
- Ensure each supporting level connects directly to the level above it
- Present ideas in order of importance within each group

4. Adapt the technical complexity based on the audience analysis:
- Adjust terminology and explanations to match audience expertise
- Include or omit technical details based on audience needs
- Use appropriate examples and analogies for the audience's background

5. Provide your summary in this structure:
- Executive Summary (1–2 sentences using the Pyramid Principle's top-level message)
- Key Points (using SQCA framework)
- Detailed Breakdown (organized using the Pyramid Principle)
- Next Steps or Recommendations

Please format the summary accordingly and ensure all technical content is appropriately calibrated for the specified audience.

The output isn’t the final product — it’s a starting point for crafting more impactful technical content. Think of it as an intelligent first draft of your transformation from exploration to influence.

It will still need a lot of work, but that objective reduction can help clarify what’s important. It also dramatically speeds up the process.

Making Technical Writing Matter

Technical expertise only creates value when it drives change. By separating the process of thinking from the act of influencing, we can create technical content that doesn’t generate those blank stares. Leveraging AI can help accelerate this time-consuming but vital process of bridging between the two.

The next time you start a technical document, ask yourself: am I just sharing my thinking, or is what I am sharing specifically created to drive change?

Using this process with our VP of Engineering allowed us to halve the length of a document in just a few minutes while strengthening its message. Afterwards he quipped on LinkedIn: “We’ve deleted a lot of code in our careers with the help of technology, but this was the first time we’ve deleted a lot of words.” He’s right — sometimes, knowing what to remove is the most valuable technical skill.

Remember: The measure of technical writing isn’t in its length or comprehensiveness. It’s the changes it generates.

Thanks David Annez, Hugo Brook, Georgia Gaskell, Jo Gostling, and George Malamidis for helping to review and improve this article 🙏