The gap you're trying to close
There's a tension built into any technical product.
R&D and marketing are good at different things, and both are necessary. Engineering produces the product; marketing is how anyone finds out it exists and why they should care. But the two groups naturally operate from different instincts. Engineers reach for architecture, internals, and precision. Marketers reach for clarity, reach, and narrative.
Those instincts don't line up on their own. Deep technical explanations overwhelm most buyers. High-level pitches leave technical buyers suspicious. And in the middle is a gap between what the product is and how customers understand what it does for them.
Closing that gap is roughly what technical marketing is for. Your job is to translate technical depth into explanations of how the product solves a real customer problem, without oversimplifying to the point where an engineer in the room rolls their eyes.
The frame I find useful for doing that is what I call the LEGO Level.
What I mean by the LEGO Level
Think about how LEGO sells its sets. The box doesn't show a pile of plastic bricks. It shows a race car, a spaceship, a castle. The pieces are present, but the thing you're being sold is what you can build with them.
That split is the part worth stealing.
A good LEGO Level for a piece of content sits at the altitude where the reader can see the outcome and the technical choices that affect it. Too high and it's a marketing brochure. Too low and it's an architecture doc no buyer will finish.
Three questions help me find that altitude.
What decision is the reader making?
Features alone don't mean much to a buyer. They become useful when they're attached to a decision the reader needs to make.
Before writing, pick a real scenario with a realistic environment and a clear before-and-after. Then work backwards from that outcome, so every feature you mention helps the reader evaluate, implement, or operate the product.
Which internals change that decision?
Internal details are useful when they change a buying decision, an implementation step, or the way someone will operate the product. Otherwise, they are probably in the wrong piece of content.
Take PDF Comments. Saying it uses React says almost nothing about whether the tool fits. Saying the PDF is processed locally in the browser matters because it changes the privacy model. Saying the parser reconstructs highlighted text from page coordinates matters when you need to explain why unusual PDFs can produce imperfect results.
My editing test is simple: does this detail change what the reader should choose, do, or expect? If not, cut it or move it to reference documentation. Architecture posts are useful; just don't disguise them as solution content.
What job does the reader have right now?
Readers do not divide neatly into two kinds of buyers. The same person can move through several jobs while considering and using a product:
- Evaluators need to understand the problem, tradeoffs, requirements, and evidence.
- Implementers need a sequenced path through configuration, integration, and validation.
- Operators need references, troubleshooting guidance, and the limits they will meet in production.
One page rarely serves all three jobs well. A product overview can help someone evaluate. A quickstart can guide the first implementation. API references and runbooks support the person operating it later. Problems start when a single article tries to be all of them at once.
Turning it into a habit
Nothing about this is a one-time exercise. A few things I try to do every time:
- Decide on the outcome before writing. A real problem, a realistic environment, a clear before-and-after. If I can't name those, I'm not ready to write yet.
- Use the customer's language. Internal feature names and project codenames creep into drafts. Replace them with whatever a new user would call the thing.
- Show the workflow. Diagrams, short walkthroughs, and code samples that mirror a real task beat isolated feature descriptions almost every time.
- Move internals out of solution content. If a paragraph is really about how something is built rather than how to use it, it belongs in a reference or architecture post.
- Publish more than one altitude. Use product overviews for evaluators, step-by-step guides for implementers, and references for operators.
The short version: stop describing the bricks. Start showing what gets built with them.