Joining a new company as a solo technical writer is always a whirlwind. But joining a company in the middle of a product pivot? That’s a masterclass in architectural agility.
Photo by Thirumalai Rajan P on Pexels.
Often, you arrive at a new job to find a product focused library. It’s a robust, detailed, and technically accurate collection of manuals that describe every knob and lever of the software. But if the company is pivoting its target audience, those “Inside-Out” docs suddenly feel like they’re speaking the wrong language.
The challenge isn’t just updating the docs, either. It’s helping the entire company align around a new path for a new kind of user. Here’s how I’m thinking through layering a persona-driven experience on top of a product-driven foundation.
The Conflict: Products vs. Personas
Product-based documentation is great for reference. If I’m a developer and I need a CLI flag, I want the CLI manual. I don’t want a story about my “user journey.”
However, product docs are terrible for onboarding. A new persona doesn’t care about “Product A” or “Product B” yet. They care about a specific outcome. If your docs are siloed by product, the user has to do the mental heavy lifting of stitching those products together to solve their problem.
The Solution: The Layered Documentation Map
To solve this without rewriting hundreds of pages of existing reference material, I’m using a layered approach. Think of it as an orchestration layer (I’m working in the Kubernetes space, after all) that sits on top of your technical repositories.
Layer 1: The Golden Path (The “Tutorial” Quadrant)
This is the “Front Door.” It is strictly persona-based. It doesn’t explain every feature; it explains the shortest path to value.
Goal: 10 minutes to an “Aha!” moment.
Focus: Cross-product workflows.
Layer 2: The Solution Context (The “Explanation” Quadrant)
This is where you answer the “Why.” Why did we build this? How does the architecture support the user’s specific goals? This layer uses the language of the company’s vision to build a bridge between the user’s problem and the technical solution.
Layer 3: The Recipe (The “How-To” Quadrant)
Once the user is onboarded, they need specific tasks. These are often product-specific but task-oriented (for example, “How to configure networking”). These guides link up to the Golden Path and down to the Reference specs.
Layer 4: The Specs (The “Reference” Quadrant)
The bedrock. These are your CLI/API/Schema docs. They remain product-focused, dry, and highly searchable.
Why This Works for Solo Writers
When you’re a team of one, you cannot boil the ocean. By layering your docs, you can:
Prioritize the Pivot: Spend your first weeks building Layers 1 and 2 (the Persona layers). This provides the most immediate value to the company and the new audience.
Protect the Truth: Leave the Product Reference (Layer 4) as the “Source of Truth” for technical details. Link to it, don’t duplicate it.
Align the Team: A persona-based Golden Path doesn’t just help users. It helps your internal stakeholders (Product, Sales, Engineering, Support, Customer Success, and so on) see exactly how the products fit together in the new world order.
Closing Thought
Documentation isn’t just a manual; it’s a map. When the destination changes (the pivot), you don’t necessarily need to pave new roads immediately. Instead, you just need to draw a better path for the people trying to get there.