Story and Structure: Building a modern technical writing portfolio

When we talk about technical writing, we often focus on the mechanics: the syntax, the tools, and the end product. We treat our portfolios the same way, as a collection of finished artifacts. We point to a polished user guide or a clean API reference and hope the work speaks for itself.

But a portfolio is more than a list of links. To someone looking to hire or partner with you, your work is only half of the equation. The other half is the structure you brought to the chaos and the story of how you got there.

A truly effective portfolio doesn’t just show that you can write, it proves that you can navigate the complex space between a product’s logic and a user’s needs.

Moving beyond the “filing cabinet”

For a long time, my own portfolio was essentially a digital filing cabinet. I was using a WordPress site that, looking back, felt very “circa 2010.” It was functional, but it was just a stagnant list of document samples and a few disconnected blog posts.

It was an archive, not a showcase. It proved I had done work, but it didn’t prove how I thought about work.

To fix it, I had to stop thinking like a librarian and start thinking like an architect. I realized that a modern portfolio needs two things: a story to explain the “why” and a structure to prove the “how.”

The story: Framing the invisible labor

The biggest mistake we make is assuming a hiring manager can look at a finished user guide and intuit the months of research, stakeholder interviews, and structural debates that went into it.

When we only show the artifact, our labor remains invisible.

To move from writer to product partner, every sample in your portfolio should be a narrative. Instead of just a link to a PDF, provide a brief case study:

• The problem: What was the specific friction point for the user?
• The solution: Why did you choose this specific format or information architecture?
• The impact: Did it reduce support tickets? Did it unblock a developer?

When you tell the story of a project, you aren’t just showing that you can write—you’re showing that you understand the business value of documentation.

Structure: Building the system

When I moved away from that WordPress site, I wanted my portfolio to reflect how I actually work. Stagnant lists didn’t feel right for building a career in the AI space.

I decided to rebuild using Astro, leaning on AI tools to help navigate the configuration and setting up a pipeline through Cloudflare. This shift wasn’t about the tools themselves. It was about adopting a docs-as-code workflow to prove technical fluency through action.

In a modern documentation landscape, your “stack” is a silent signal. This approach shows a partner three things:

• Technical fluency: Navigating a repository is a core skill. When your portfolio lives in one, you show you can thrive in a developer’s environment.
• Practical AI use: Working in AI means knowing how to use it as a force multiplier. Using it to bridge gaps in a build process shows you know how to ship a high-quality product.
• Deployment awareness: Setting up a pipeline proves you understand how content moves from your local machine to the user.

Moving to this structure was the final piece of the puzzle. It turned my portfolio from a static archive into a professional’s toolkit.

Putting it into practice

Shifting your perspective is the first step. The next is the actual labor of building. If you are looking to move away from a stagnant archive and toward a modern, story-driven portfolio, here is where I suggest you start.

Building the story

You don’t need twenty samples. You need three or four that you can speak about with depth.

This is often harder than it sounds. Many of us—myself included—have been caught off guard by layoffs or restructuring, only to realize our best work vanished along with our corporate credentials. When you lose access to your work overnight, you realize that a portfolio built on live links is a house of cards.

The lesson learned: Capture your work as you go. Don’t wait for a project to be finished or for your tenure to end. Take the screenshots, save the clean PDFs, and document your logic while it’s fresh. Treat these as your personal “artifacts of record” so you aren’t dependent on a URL that could disappear tomorrow.

If you are currently rebuilding from memory, focus on these specific tactical steps to recreate your narrative:

• Audit your mental archive: List projects where you were the primary driver of a structural change. Focus on the “migration” stories—moving from a legacy wiki to a docs-as-code site, or untangling a disorganized API reference. These are high-value signals to a potential partner.

• Draft a 3-sentence problem statement: For each project write a problem statement that includes the symptom, the root cause, and the cost.
  ”New developer onboarding was taking an average of three weeks to complete. The root cause was a fragmented environment setup guide scattered across four internal wikis. This resulted in dozens of redundant support tickets and a significant drain on senior engineering time.”

• Visualize the structural logic: If the original site is gone, use whatever diagramming tool you are comfortable with to recreate the sitemap or the information architecture. Map out how you moved from a flat list of files to a nested, logical hierarchy. Showing a “before and after” of a navigation menu or a document tree proves you can organize complex data, even if you can’t show the text within the folders.

• Quantify the shadow metrics: You might not have the official Google Analytics data anymore, but you remember the qualitative wins. Did support tickets drop? Did the engineering team stop asking the same three questions in Slack? Document those internal shifts as your Impact section.

Building the structure

The goal of your portfolio infrastructure is to provide tangible evidence of your technical fluency before a partner even reads a single word of your content. By choosing a stack that requires actual configuration and deployment, you are sending a silent signal about your ability to navigate the tools that engineering teams use every day.

• Docs-as-code workflow: Move your writing into a Git repository. You don’t have to make your repo public immediately if you are still “building in the dark” or have messy commit messages. However, if you do share your GitHub link with an employer, keep in mind that they can see your habits. Use a tool like Squash and Merge to clean up a messy history before it hits your main branch. This shows you understand how to maintain a clean, professional commit history that other developers can actually follow.

• Modern frameworks: Research the strengths of different tools based on your current technical comfort and where you want to grow. Jekyll is the classic choice if you want something stable and straightforward that integrates natively with GitHub Pages. Docusaurus is the industry standard for “out-of-the-box” documentation features like versioning and search. If you want to stretch your abilities, Astro or Next.js will force you to learn more about modern web components and performance. Treat this selection as a learning exercise. The goal is to choose a tool that challenges you to learn a new skill while still allowing you to get the content live.

  1. Check the starter templates: Go to the Themes or Showcase section of each framework. If you can’t find a template that looks like a professional documentation site, it’s going to be an uphill battle to build one from scratch.
  2. Read the Getting Started docs: Ironically, the best way to pick a documentation tool is to read their documentation. If their setup guide is confusing to you, it’s a sign that the tool might be more complex than you need.
  3. Map the skill to the market: If you see Docusaurus in every job description you like, that’s your signal to use it, even if the learning curve is steeper.

• Automated pipelines: Connect your repository to a platform like Cloudflare to handle your deployment. I originally started on GitHub Pages, but I quickly realized that a growing portfolio can eat through your monthly GitHub Action minutes or fail during a build because of heavy image assets. Moving to Cloudflare allowed me to offload those images and keep the site fast, all within their generous free tier. Setting this up proves you understand the CI/CD lifecycle and can troubleshoot infrastructure bottlenecks when a simple setup reaches its ceiling.

• AI as a force multiplier: Use tools like ChatGPT or Claude to bridge the gaps in your technical knowledge. I used AI to troubleshoot everything from stubborn CSS layouts to specific syntax questions, like how to write an Astro component for a link that opens in a new tab. Don’t feel like you have to be a senior developer to build a great site. Using AI to generate configuration files or to explain a build error shows you know how to use modern tools to solve problems and ship a high-quality product.

Final thoughts: Ship the first version

Building your portfolio this way transforms it from a static record of the past into a live demonstration of your current value. Every architectural choice you make—from the way you structure your Git commits to the global scripts you write to improve user experience—serves as a high-fidelity preview of how you will show up on day one.

The greatest asset of a technical writer isn’t just knowing a specific tool. It’s the ability to dive into the unknown and learn a new system from the ground up. If you don’t have a portfolio yet, or if yours feels like a dusty filing cabinet, let this be your permission to start over. Don’t be afraid to break things. The struggle of setting up your first pipeline or debugging a stubborn layout isn’t a distraction, it’s the training ground for your next role.

The portfolio you build today is more than just a home for your writing. It’s a foundation you can continue to build on. Start small, stay curious, and show the world exactly how you bridge the gap between a problem and a solution.