This post is part of the Per the Docs article series. Links to the rest of the series are at the end of this piece.

• The Oxford comma is non-negotiable
• The Strangler Fig problem
• Sally in accounting
• "Unable" - I can't
• The -ing problem
• What happens when you work with AI

The Oxford comma is non-negotiable

Experienced writers follow style guides, and they know when to break the rules. It's a skill of its own to understand the intent behind the rules well enough to recognize when following them works against the reader.

For example, I'm currently required to apply the AP style guide in my work. The AP doesn't use the Oxford comma. But for technical content, I do... always.

The Oxford comma prevents ambiguity in lists, and ambiguity in technical documentation has consequences. "Scope includes admin, read and write access." Is that three scopes, or two, where read/write is a paired permission level? The same ambiguity appears in "The API removes the primary record, the secondary pointer and child objects." Are we talking about secondary pointers and secondary child objects, or secondary pointers and all children? In access control and data deletion, that's not a question you want readers to answer for themselves.

I follow the spirit of a style guide: consistency, clarity, and respect for the reader. When a specific rule works against those goals, I make a conscious decision to override it and I'm prepared to defend that decision.

The Strangler Fig problem

One of the trickiest judgment calls in technical writing is knowing when to use the right term versus the useful term. Subject matter experts often want documentation to reflect their vocabulary. But experienced writers know that doesn't always align with the reader's vocabulary.

I recently rewrote the deployment instructions for a software system. The internal team had described the migration approach as a "Strangler Fig pattern" and used that phrase in the first rev of the docs. It's a legitimate software architecture concept where a new system gradually replaces an old one by wrapping around it. The term is technically accurate and completely correct, but entirely wrong for the audience.

The people reading the deployment guide need to understand how the migration works, but introducing this pattern name requires readers to first learn what a strangler fig tree is, understand why that metaphor applies to software architecture, and then finally arrive at the concept itself. That's two layers of context the reader has to climb before they reach information they can use.

Directly describe the behavior to get them there in one step: the system transitions gradually, and existing functionality remains available while new components are introduced. Easy peasy.

Sally in accounting

Read the room. It's an essential skill that a writer needs to have, and one of the hardest to teach. It's the ability to sense who's in the audience and write accordingly.

When I wrote documentation for SugarCRM, I developed an imaginary user I called Sally in accounting. Sally is intelligent, capable, and completely non-technical. She uses the CRM every day to do her job and has zero interest in how it works under the hood. She just needs it to work.

Nobody told me to think about Sally. No brief mentioned her. But I knew she was in the audience, and she shaped every word I wrote. I'd ruthlessly eliminate jargon, lead with outcomes rather than mechanisms, and ask whether someone without technical context could successfully act on what I'd written.

As writers, we need to sense who's in the audience, even when nobody tells us explicitly.

"Unable" - I can't

Some tacit knowledge shows up as a persistent editor reflex. It's something you fix automatically across every draft you touch, without ever having formalized it as a rule.

The word "unable" is one of mine. It's passive, slightly formal, and creates distance between the reader and the action. "You are unable to proceed" becomes "you can't proceed." Just a tweak, but a massive difference in tone. I've never written this down as a rule, but I fix it every time.

The -ing problem

Two standard style guide rules operate together here:

If a task has a qualifier, lead with it. The goal or condition belongs at the beginning of the sentence, not the end. The reader needs context before instruction.

Use -ing words with care. A word that ends in -ing can be a verb, a noun, or an adjective, and this ambiguity creates risk. "By doing this, you can do that" breaks both rules at once. It buries the goal at the end and introduces an -ing word that could be read multiple ways. "To do that, try this" fixes both problems.

Both of these rules appear in the Google Developer Style Guide and the Microsoft Style Guide, but they're surprisingly overlooked by even experienced writers. I'm pedantic enough about these that I run a Ctrl+F for "ing" on every page I touch (don't do that on this blog post please - I'm referring to formal docs!). Gerund abuse and misplaced qualifiers tend to travel together. This thirty-second search is a standard part of my editing pass.

What happens when you work with AI

I've used AI tools heavily in my work for the past few years, and the collaboration has sharpened my understanding of tacit knowledge. AI will do what you ask. It follows the rules. Unlike humans, it's relentlessly consistent. This consistency means that it regularly produces output that a writer immediately knows is just plain wrong.

A few examples from my own workflow:

• I asked an AI to restructure an API reference for scannability. The result was technically well-organized. I rewrote it anyway, because the restructure had broken the logical progression a that developer needs to understand the underlying model before the reference makes sense.
• I asked an AI to clean up passive voice throughout a set of procedures. It did. I put some of it back, because active voice in certain warning contexts implies user agency where there isn't any. "This action can't be undone" is more accurate than "you can't undo this action" when the system is the one that enforces the constraint, not the user's decision.
• I reviewed microcopy for a deletion confirmation where AI-generated copy used the phrase "you can't recover this item." True, but recover is ambiguous. It could mean the item can't be restored after deletion, or it could mean the item can't be recreated at all. Those are very different things.

In each case, the fix came from my years of watching how people read, misread, and act on documentation.

LLMs are remarkably good at following explicit rules. Feed one your style guide and it will apply it more consistently than humans will. But tacit knowledge is different. It's knowing when a technically correct term will create unnecessary cognitive load, when a style guide rule works against clarity, who's reading and what they really need to know (and what they don't), and what's wrong with a sentence before you can articulate why.

The fact that a writer's knowledge resists codification is what makes it valuable. Style guides capture what can be taught. Experienced writers carry what can't. Our craft lives within this gap.

This post is part of Per the docs, a monthly collaborative series where technical writers explore different aspects of our craft. Each month features a new topic with perspectives from writers across the community. Read more perspectives in the series:

April 2026 topic: Mind the Gap

• Previous post: James Beach - Find it to Mind it: Taxonomies as Gap-Finders →
• Next post: Nicholas Galinski - Don't turn off your brain →

View all participants in this month's hop →

Disclaimer: Each article in this series is written and owned by its respective author. The views, opinions, and experiences shared belong solely to the individual writer and do not represent the perspectives of other participants or their employers (past or present).

Per the docs is a monthly article series where technical writers explore various aspects of our craft. Each month, a different host curates a topic and brings together diverse voices to share insights, experiences, and practical advice.

Want to follow along or contribute to a future edition? Everything you need is at perthedocs.com: past themes in the archive, contributor guidelines in the writer portal, and information about joining the community.

April 2026 topic: Mind the gap

Where do the docs end and the user's assumption begin? this month, we're exploring what isn't written: missing context, assumed knowledge, and gaps that reduce time-to-success.

Brandi Hopkins

Brandi is a senior documentation strategist who builds scalable content systems, with expertise in docs-as-code workflows, AI-assisted documentation, and developer experience.

Read their post: Auditing the Gaps: A content analysis approach for inherited docs →

brandihopkins.com | LinkedIn

James Beach

James is a content strategist and technical writer with a knack for prompt engineering and AI-assisted workflows — always finding new ways to bridge the gap between ideas and execution.

Read their post: Find it to Mind it: Taxonomies as Gap-Finders →

jamesmbeach.com | LinkedIn

Jill Shaheen

Jill is a documentation leader who's been building content systems, leading documentation teams, and figuring out where infrastructure breaks for nearly 20 years.

Read their post: Unwritten rules that tech writers follow →

jillshaheen.com | LinkedIn

Nicholas Galinski

Nick is an M-shaped multidisciplinary writer, content designer, systems architect, and AI-fluid storyteller. Turning complex problems into elegant narratives while leading with empathy.

Read their post: Don't turn off your brain →

nicholasgalinski.com | LinkedIn

Reem Sabawi

Reem is a former AWS technical writer, founder of Reem The Writer, and builder of DocSentinel AI. She writes about documentation strategy and the knowledge layer that makes AI reliable.

Read their post: You are not the show →

reemthewriter.substack.com | LinkedIn

Disclaimer: Each article in this series is written and owned by its respective author. The views, opinions, and experiences shared belong solely to the individual writer and do not represent the perspectives of other participants or their employers (past or present).

This post is part of the Per the Docs article series. Links to the rest of the series are at the end of this piece.

Most technical writers are using AI tools. We have Copilot, Claude, and ChatGPT in our daily workflows, helping us draft, edit, summarize, and brainstorm. But using AI tools and building AI workflows are two different things.

It's time to learn how to design systems that work without the writer in the loop. Not just how to use AI tools, but how to build workflows that make reliable decisions, retrieve the right context, and produce consistent outputs at scale. Then you'll be free to focus on strategy, stakeholder relationships, content architecture, and the judgment calls no agent can make.

When you're using AI tools within a workflow, you're the one orchestrating every step, evaluating every output, deciding what comes next. The AI waits on you between each task.

For example, you paste a support ticket into Claude and ask it to suggest a doc update. The AI handles that task and then waits for you.

In an agentic workflow, the AI orchestrates the steps itself. You give it a goal, and it plans a sequence of actions, decides which tools to call, evaluates its own outputs, and adjusts course based on what it gets back. Building agentic workflows requires you to design systems that make reliable decisions without a human at every step.

A big thing to unlearn is your assumption about stability. A document has a fixed audience and a stable context. An agentic workflow has variable inputs, multiple decision points, and behavior that shifts depending on what the model retrieves. If you're trying to treat an agentic workflow as something you can finalize, it just doesn't work that way.

How MCP changes the way we need to think

MCP lets AI models connect to external tools, data sources, and services in a structured way. With MCP, an agent can reach outside itself to query a database, read a file, call an API, or trigger an action. Instead of a model working only from what's in its context window, MCP pulls in the right information at the right moment.

For writers, this matters because documentation is a data source. Knowledge bases, style guides, API references, and release notes all become something an AI agent can retrieve, reason over, and act on. It's a fundamentally different relationship between content and AI than "paste this into ChatGPT and ask it to improve the tone." Once you understand that, you'll stop thinking about content as something you produce, but as something a system consumes.

In practice

Let's imagine we're creating a release notes generator. You need an agent to monitor a GitHub repository for merged pull requests, retrieve ticket details from Jira, cross-reference your style guide, draft release notes in the proper voice, and then route the draft to a writer via Slack.

Here's how you might build it:

GitHub Actions or n8n detects the merged PR and kicks off the workflow. n8n calls Claude, which uses MCP to pull the PR details from GitHub and ticket context from Jira. Claude drafts the release notes. n8n routes the draft to Slack.

Jot down a clear goal and define the inputs and outputs. What triggers the workflow? What does "done" look like? Keep it tight. GitHub Actions can handle the trigger logic, and tools like n8n or Make can help you map the full workflow on a visual canvas before you write out your instructions.

Next, identify the tools that the agent needs to connect to and wire them up. This is where MCP comes in. Claude with MCP servers gives you structured, reliable connections to GitHub, Jira, your docs repository, and Slack without one-off integrations.

1. Get started on Claude Desktop or Claude Code. Both support MCP server configuration through a JSON config file. You add server definitions for each tool you want to connect, provide API credentials, and Claude can then interact with those tools directly.
2. Connect GitHub first. GitHub has an official MCP server maintained by Anthropic. It's the most stable starting point and handles pull requests, issues, and repository operations. Test it with a real task. Ask Claude to list your open pull requests or summarize recent commits on a repo you own. If it works, you have a functioning MCP connection.
3. Add Jira after GitHub is working. Jira has a couple options. The most popular community option is mcp-atlassian, which covers both Jira and Confluence and uses your Atlassian URL and API token for authentication. The official Atlassian MCP server also exists but has had some reported authentication stability issues.
4. Once you've confirmed that Jira is set up, connect to Slack's official MCP server, available through the MCP servers registry.
5. For your docs repository, if it's on GitHub that's already covered. If it's Confluence, mcp-atlassian handles that too.
6. Finally, set up n8n or Make for automation. MCP handles the connections. n8n handles the orchestration.

Now you can write the prompt strategy, or the instructions that tell the agent how to reason across the data it retrieves from each connected tool. Prompt strategies feel like writing. Define the tone, scope, what to include, what to skip, how to handle edge cases like incomplete tickets or features that touch multiple services.

What you might not know how to do yet is handle failure at the system level. A prompt that works perfectly in isolation breaks when an agent is chaining multiple steps. Context that seems obvious to a human reader is invisible to a model that only sees what you explicitly provide. Small ambiguities compound in ways they never do in a static document.

Understand that when the agent breaks, it's because you've underspecified something. Treat prompts the way you treat documentation: validate against real conditions. Test against messy merged PRs, tickets with missing fields, and features that span multiple teams. Each break is a lesson in where your instructions are falling short.

What I had to learn

I assumed my existing skills would transfer cleanly to agentic workflows. And they partially did. The writing instincts that help me anticipate a reader's confusion translate well to designing prompts. I'm still asking: what does this system need to know, in what order, and where will it go wrong if I leave something out?

The instinct to anticipate failure modes is already there. Technical writers spend years thinking about what a user will misread, skip, or misapply. We also know how to connect systems. We've been building with APIs, webhooks, and automation tools forever.

But connecting systems for humans and designing systems for AI agents are different problems, so I had to learn to validate at the system level, not just the sentence level. I didn't fully appreciate that until I started working with MCP.

What you need to do right now

Based on my own path, a few things will make the biggest difference when you make the shift:

• Understand that an AI model can only work with what fits in its context window at one time, and that space fills up quickly when an agent is juggling multiple tools and steps.
• Get hands-on with at least one agentic tool beyond a standard chatbot interface.
• Build something small that solves a real problem.
• Document what breaks.

The writers who understand how AI systems actually work will be the ones who define how AI systems behave in production. You need to design in reliability, consistency, and usefulness from the start, then iterate as you go. It's a technical writing problem, and we're well-positioned to solve it. Now stop using and start building!

This post is part of the Per the docs article series, a monthly collaborative series where technical writers explore different aspects of our craft. Each month features a new topic with perspectives from writers across the community.

• Previous article: Shelby White - Getting started with Github
• Next article: Brandi Hopkins - Professional Development for Technical Writers: What to invest in as your career evolves

See the full list of participants and articles →

Disclaimer: Each article in this series is written and owned by its respective author. The views, opinions, and experiences shared belong solely to the individual writer and do not represent the perspectives of other participants or their employers (past or present).

More in the docs-as-code series:

• Git hygiene for technical writers — Best practices for a smooth start in Git-based documentation.
• What to expect when you're expecting docs-as-code — A field guide for writers new to Git-based workflows.

This article covers environment-specific and markup-specific gotchas. For fundamental Git workflow practices like branching strategy, commit messages, pulling frequently, and handling merge conflicts, see my companion post Git hygiene for technical writers.

In this article:

• The hidden .gitignore file
• Your editor config matters
• You can't delete history (and that's good)
• Trailing spaces break cross-references
• Build times vary wildly
• Documentation lives with code
• Pull request review isn't universal
• Platform-specific features don't transfer

Gotcha #1: The hidden .gitignore file

.gitignore tells Git which files not to track or commit. In docs-as-code workflows, this usually includes generated build files, dependency folders, caches, logs, and local configuration files. These files are either machine-specific or automatically generated, so they don’t belong in version control.

Why it matters: If a file isn’t showing up in git status, or a change seems to disappear, it might be intentionally ignored. This helps keep pull requests focused on real documentation changes and prevents accidental commits of noisy or sensitive files.

Common examples in docs projects:

• Build output folders like /build, /site, or /public
• Dependency folders like node_modules
• Temporary files, caches, and logs
• Local environment files such as .env

How to use it

You usually don’t need to create a .gitignore from scratch. Most repos include one already, tailored to the tools they use. As a tech writer, your job is to understand what it’s doing.

• If a file isn’t being tracked, check .gitignore before assuming Git is broken.
• Don’t remove ignore rules just to make Git "see" a file. Ask whether that file should really be committed.
• When adding new tools (for example, a local preview server or build step), you might need to add new ignore rules for their generated files.

Learn more: Official Git documentation on .gitignore and GitHub’s collection of .gitignore templates are excellent references when you’re unsure what should (or shouldn’t) be ignored.

Gotcha #2: Your editor config matters

Different editors have different defaults for tabs vs. spaces, file encoding, and line endings.

Fix: Create an .editorconfig file in your repository root:

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

This makes everyone's editor behave consistently.

Gotcha #3: You can't delete history (and that's good)

Once you commit something, it's in the Git history forever. Even if you delete it in the next commit.

Implication: Don't commit passwords, API keys, or sensitive information. Ever.

If you do: Tell your security team immediately. The repository needs special cleanup.

Gotcha #4: Trailing spaces break cross-references

Trailing whitespace inside attribute values can break cross-references and links. How much this matters depends on your markup language.

XML/DocBook (strict): Parsers treat extra space as part of the unique identifier. The link <xref linkend="section-id"/> fails to match the target <section id="section-id "/> because "section-id" and "section-id " are different identifiers.

Markdown (forgiving): Generally handles whitespace gracefully, though reference-style links can fail if the reference ID has trailing spaces.

HTML (somewhat forgiving): Fragment links like <a href="#section-id "> won't match <div id="section-id">, but HTML parsers are more lenient than XML parsers.

The problem in XML (shown as example):

<!-- Broken: space in the link reference -->
<xref linkend="section-id "/>

<!-- Broken: space in the target ID -->
<section id="section-id ">

<!-- Works: no trailing spaces -->
<xref linkend="section-id"/>
<section id="section-id">

Why it happens: XML parsers don't automatically trim whitespace from attribute values. An ID like id="chapter1 " is treated as completely different from id="chapter1". The build system looks for an exact match and can't find it.

Symptom: Links that look fine in your editor don't work in the built documentation. Cross-references render as plain text instead of hyperlinks. Build validation might report "target not found" errors even though you can see the target right there in the source.

Prevention (works for all markup languages): Configure your editor to show whitespace characters and trim trailing spaces on save.

In VS Code:

"files.trimTrailingWhitespace": true,
"editor.renderWhitespace": "all"

In Oxygen XML Editor: Enable "Show whitespace" in preferences and set "Remove trailing whitespace" in formatting options.

Advanced fixes for XML: If you're building XSLT transformations or XML processing pipelines, use <xsl:strip-space elements="*"/> to remove unnecessary whitespace during transformation. For JSON-to-XML converters or other XML generators, configure them to trim leading and trailing whitespace from attribute values before output.

My experience: This caused so many mysterious build failures for me. I'd commit what looked like a perfect link, but the build would fail or the link wouldn't work. The space inside the quotes is nearly invisible but completely breaks ID matching. I learned to always enable whitespace visualization in Oxygen and to configure automatic trimming on save. The problem can be on either end of the reference—in your linkend attribute or in the target's id attribute. Both need to be clean.

Gotcha #5: Build times vary wildly

If your docs-as-code system has a local build command, use it. But understand that local builds and production builds can be very different experiences.

Why: You'll catch broken links, syntax errors, and formatting problems before they hit the repository. But local builds might complete in seconds while production builds take hours.

My experience: Our local Oxygen builds were nearly instant. You could see your XML render immediately. But pushing to the internal Git farm triggered a custom build system that could take 2-4 hours to fully propagate changes to the public doc site. This created a workflow challenge. You couldn't quickly iterate on customer-facing changes. Every push needed to be carefully tested locally first.

What to ask in interviews: "How long does a typical build take from merge to live?" and "Can I preview changes before they go live?" These answers will tell you a lot about your day-to-day experience.

Typical commands:

# Test the build locally
make build

# Or
npm run build

# Or whatever your system uses

Gotcha #6: Documentation lives with code

In many docs-as-code setups, your documentation files live in the same repository as the actual product code.

Implication:

• You'll see code files you don't need to touch
• Builds might include compiling actual software
• You need read access to proprietary code

Navigation tip: Learn the repository structure early. Know where docs live vs. code.

Gotcha #7: Pull request review isn't universal

Many docs-as-code guides assume every change goes through pull request review. This isn't always true.

Why it matters: You might see job descriptions or tutorials that emphasize peer review workflows, but the actual practice varies widely by company and team.

My experience: Our Git system supported Change Requests (CRs, basically pull requests), but most writers merged their own work without review. If you owned your docs package, you were trusted to maintain quality independently. Review workflows existed but were optional.

What to ask in interviews: "What's your review process for documentation changes?" The answer tells you about trust levels, team size, and quality assurance practices.

Gotcha #8: Platform-specific features don't transfer

GitHub has features like Actions, Projects, and Discussions. GitLab has different features. Internal Git systems have their own custom tooling.

Why it matters: When you switch companies or platforms, you're learning that platform's entire content ecosystem.

My experience: I got very comfortable with our internal review system, build triggers, and preview tools. Now when I look at GitHub repositories, I'm relearning how to set up Actions, understand Checks, and use Projects. The Git fundamentals (commit, branch, merge) are identical. The platform features are completely different.

What this means: Don't assume your docs-as-code experience at one company will transfer perfectly to another. The core Git skills do transfer. The platform-specific workflows don't.

You got this

After years of managing writers in docs-as-code environments, I can tell you this: everyone hits these gotchas. Senior developers who've used Git for a decade still Google how to fix merge conflicts. Experienced technical writers still lose time to trailing spaces in XML attributes.

The difference between a frustrating experience and a productive one is knowing these problems exist and having the fixes ready.

Most of these issues have straightforward solutions:

• Configure your editor once to show whitespace and trim trailing spaces
• Learn your .gitignore and .editorconfig files
• Pull frequently, push infrequently, delete merged branches immediately
• Ask about platform-specific features in interviews

You won't avoid all of these problems. But you'll spend minutes fixing them instead of hours wondering what's wrong.

The goal isn't Git expertise. The goal is comfortable productivity. Know where the invisible obstacles are, and docs-as-code becomes infrastructure you barely think about.

More in the docs-as-code series:

• Git hygiene for technical writers — Best practices for a smooth start in Git-based documentation.
• Docs-as-code gotchas for technical writers — Avoid the most common pitfalls when working in docs-as-code environments.

In this article:

• What docs-as-code means
• The toolchain: What you need
• Your typical day: Actual workflow
• The learning curve: What gets easier
• Working with other writers: Collaboration patterns
• What success looks like
• Making the transition
• The benefit nobody talks about

What docs-as-code means

Docs-as-code means treating documentation like software developers treat code:

• Files live in version control (usually Git)
• Changes go through review processes (pull requests)
• Multiple people work on the same files simultaneously
• Automated systems build and deploy your content

That's it. You're learning developer workflows, not becoming a developer.

What you get:

• Complete change history (who changed what, when, and why)
• The ability to work in parallel without stepping on each other
• Automated checks before content goes live
• Integration with the same systems engineers use

The toolchain: What you need

Required tools

Git - Version control system that tracks changes to your files

• Think of it as Track Changes on steroids
• Works from command line or GUI tools
• Stores complete history of every change

Text editor or IDE - Where you write

• VS Code is popular (free, extensions for everything)
• Oxygen XML Editor (powerful but pricey)
• Atom, Sublime, IntelliJ, or whatever you like
• Key feature: integration with Git

My experience: I used Oxygen XML Editor at my job, which has built-in Git integration. You could commit, push, and pull right from the editor without touching the command line if you wanted to, but I enjoy the unbridled power of the CLI. Now that I'm exploring other companies' toolchains, I like to use VS Code with its built-in terminal. And the many available extensions give you functionality that's similar to Oxygen for free.

Markdown or similar - Lightweight markup language

• Plain text with simple formatting codes
• **bold** becomes bold
• # Heading becomes a heading
• Learn the basics in 30 minutes

XML (or similar structured markup) - More robust markup for complex documentation

• DocBook XML is common for technical documentation
• DITA (Darwin Information Typing Architecture) for modular content
• Custom XML schemas specific to your company
• More verbose than Markdown but handles complex structure better

My experience: My team used a customized version of DocBook XML, which Oxygen XML Editor handled beautifully. The verbosity takes getting used to after Markdown, but XML schemas enforce consistency and enable sophisticated content reuse. Many companies are moving toward Markdown for simplicity, but XML is still prevalent in enterprise documentation.

Common additional tools

GitHub/GitLab/Bitbucket - Web platforms for Git repositories

• Where your files live
• Where you submit changes for review
• Where you collaborate with team
• Note: Some companies use internal Git servers instead of public platforms

My experience: We had an internal Git farm (not GitHub), so everything lived behind the corporate firewall. The Git commands were identical, but the web interface was custom-built. Now I'm relearning GitHub-specific features like Actions, Projects, and the slightly different pull request workflow. The core concepts transfer completely. It's just the UI that's different.

Build tools - Systems that turn your source files into websites

• Hugo, Jekyll, Sphinx, or custom systems
• Usually configured by someone else
• You just need to know basic commands
• Critical reality check: Some builds are fast (seconds), some are slow (hours)

My experience: We had a custom build system that could take hours to fully propagate changes to the public docs site. You'd push a change in the morning and check back after lunch to see if it appeared. This meant you couldn't iterate quickly. Every change required planning. Some companies have builds that complete in seconds. Ask about this in interviews. Build speed dramatically affects your workflow and stress levels.

Static site generators - Create websites from your Markdown

• Convert your files to HTML
• Apply styling automatically
• Generate navigation and search

Your typical day: Actual workflow

Here's what working in docs-as-code actually looks like:

Morning: Sync and plan

# Update your local copy with latest changes
git pull origin main

# See what changed overnight
git log --oneline --since="yesterday"

You're checking what your teammates changed while you slept. No different from checking email or Slack. Takes 30 seconds.

Mid-morning: Create your working branch

# Create a branch for your work
git checkout -b js-add-authentication-docs

Branches let you work independently. You can make any changes you want without affecting anyone else. Your teammates do the same. When everyone's ready, you merge the changes together.

Branch naming tip: Prefix with your initials and use descriptive names like js-add-authentication-docs or js-DOC1234-authentication. You'll be juggling multiple branches, and good names help you find the right one quickly.

All day: Write and commit

<!-- You write in your text editor -->
<!-- In Markdown: -->
# API Authentication

To authenticate requests, include your API key in the header:

`Authorization: Bearer YOUR_API_KEY`

<!-- Or in DocBook XML: -->
<section xml:id="api-authentication">
  <title>API Authentication</title>
  <para>To authenticate requests, include your API key in the header:</para>
  <programlisting>Authorization: Bearer YOUR_API_KEY</programlisting>
</section>

# Save your changes periodically
git add .
git commit -m "Add authentication section to API docs"

# Pull from main frequently to stay current
git pull origin main

Committing is like saving versions of your Word doc, except each version has a description of what changed. You can always go back to any previous version.

Best practice: Commit often with small, meaningful changes. Pull from main throughout the day to avoid nasty merge conflicts later. The more frequently you pull and merge, the easier conflicts are to resolve.

Afternoon: Get feedback

# Push your branch to the server
git push origin js-add-authentication-docs

This is the stage where you seek feedback from technical reviewers, editors, or peer writers. The process is often iterative:

1. Submit your changes for review (via pull request, change request, or shared branch).
2. Reviewers (tech leads, editors, or peers) provide comments, suggestions, or edits.
3. You incorporate their feedback, make revisions, and update your branch.
4. Repeat the review cycle as needed until all feedback is addressed and reviewers approve the changes.

Depending on your team, this may involve multiple rounds of feedback, especially for complex or high-visibility documentation. Editors may create a separate branch for markup, or leave inline comments in your pull request. Peer review is common in larger teams, while solo writers may self-review or rely on editor feedback.

Best practice: Treat feedback as a collaborative process. Ask clarifying questions, discuss suggestions, and make sure all technical and editorial concerns are resolved before merging.

Only after all feedback is incorporated and reviewers are satisfied should you proceed to merge and deploy your changes.

End of day: Merge and deploy

Once your work is ready, you merge your branch. Your changes go live.

Automated systems:

• Run quality checks
• Build the documentation site
• Deploy to production

You watch it happen. You don't make it happen.

Important: Delete your branch immediately after merging, both locally and on the remote. Do it right then while you're thinking about it. Otherwise you'll accumulate dozens of stale branches cluttering your workspace.

# After merge, delete the branch
git branch -d js-add-authentication-docs
git push origin --delete js-add-authentication-docs

The learning curve: What gets easier

Week 1: Everything feels awkward

• You'll use cheat sheets constantly
• Every command requires looking something up
• You'll accidentally commit things you shouldn't

Month 1: Basic workflows become automatic

• Clone, branch, commit, push feels natural
• You stop panicking about merge conflicts
• You can help newer teammates

Month 3: You're spotting efficiency gains

• You know when to rebase vs. merge
• You create aliases for common commands
• You're suggesting workflow improvements

Month 6: You forget you were ever intimidated

• Git becomes invisible infrastructure
• You focus on content, not tools
• You wonder how you ever worked without it

Navigation tip: Learn the repository structure early. Know where docs live vs. code.

Working with other writers: Collaboration patterns

What success looks like

After three months in docs-as-code, you should:

• Clone a repository without looking up commands
• Create branches, commit changes, and push them confidently
• Review pull requests and leave meaningful comments
• Resolve simple merge conflicts independently
• Know when to ask for help vs. Google it

You won't know everything. Nobody does. Developers who've used Git for years still Google commands.

The goal isn't Git expertise. The goal is comfortable productivity.

Making the transition

If you're just starting

1. Install Git and a text editor (VS Code is fine)
2. Take a GitHub Skills course (free, interactive, 30 minutes)
3. Practice with a personal project before touching work files
4. Ask teammates for their cheat sheets (everyone has them)
5. Commit early and often (small commits are easier to understand)

If you're switching platforms

Moving from one docs-as-code system to another? Here's what I'm learning:

1. Core Git skills transfer perfectly - commit, branch, merge, pull, push work identically
2. Platform features don't transfer - GitHub Actions ≠ my old internal build triggers
3. Give yourself grace - You're not starting over, but you are learning new tools
4. Your editor might change - Oxygen → VS Code means relearning keyboard shortcuts
5. Build times might shock you - Hours → seconds feels magical; seconds → hours feels painful

What I wish I'd known: When I started interviewing, I undersold my Git experience because I'd only used an internal system, not GitHub. That was a mistake. Git is Git. The commands are identical. I just needed to learn GitHub's UI, which took about a week.

Questions to ask: When interviewing at new companies, ask about their review process. "Do writers merge their own work or is peer review required?" and "How are edits handled?" These answers reveal team culture, trust levels, and your actual day-to-day workflow.

If you're struggling

1. You're not alone - Every writer goes through this
2. GUI tools help - GitHub Desktop, Sourcetree, GitKraken make it visual
3. Command line comes later - Start with GUI, graduate to terminal when ready
4. Mistakes are recoverable - Almost nothing is permanent
5. Your teammates want you to succeed - They've been exactly where you are

Resources that help

For Git basics:

• GitHub Skills (interactive tutorials)
• "Git for Humans" by David Demaree (book)
• Oh Shit, Git!?! (ohshitgit.com) - fixes for common mistakes

For Markdown:

• Markdown Guide (markdownguide.org)
• Your first draft (just start writing, look up syntax as needed)

For XML/DocBook:

• DocBook: The Definitive Guide (docbook.org)
• Your company's schema documentation (every implementation is different)
• Oxygen XML Editor tutorials (if you're using Oxygen)

For build tools:

• Your team's documentation (every system is different)
• README.md in your repository (usually has setup instructions)

The benefit nobody talks about

Docs-as-code gives you one thing that traditional tools don't: evidence of your work.

Your Git history becomes a portfolio. Every commit shows:

• What you changed
• Why you changed it
• How it improved the docs

When performance review comes, you have metrics. When you apply for your next job, you can point to real contributions in public repositories.

Traditional docs tools hide this evidence. Docs-as-code makes it visible.

You've got this

Docs-as-code isn't about becoming a developer. It's about using developer tools to make collaboration easier and documentation better.

The learning curve is real. But it's not steep. And the payoff (better collaboration, clearer history, automated quality checks) makes the investment worth it.

Whether you're starting fresh, switching from traditional tools, or moving between docs-as-code platforms (like I am), the fundamentals stay the same. Git is Git. The platforms just wrap different features around it.

Start small. Be patient with yourself. Ask questions.

In six months, you'll wonder why anyone still uses anything else.

A note on platform switching: If you're experienced with one docs-as-code system and worried about learning another, don't be. I spent years in an internal ecosystem with Oxygen and custom build tools. Now I'm relearning GitHub. The Git commands are identical. I'm just learning different UI buttons and platform features. Your docs-as-code experience absolutely transfers. You're just learning a new interface on skills you already have.

More in the docs-as-code series:

• Docs-as-code gotchas for technical writers — Avoid the most common pitfalls when working in docs-as-code environments.
• What to expect when you're expecting docs-as-code — A field guide for writers new to Git-based workflows.

That first week in a Git-based documentation environment can feel overwhelming. Branches everywhere, merge conflicts appearing out of nowhere, and that nagging feeling that you're about to break something important.

Here's your Day 1 survival guide.

Start with a cheat sheet, keep it forever

The single best thing you can do is maintain a personal Git cheat sheet. Not a generic one from the internet, but your cheat sheet with the exact commands you use in your specific environment.

Keep it open constantly. Update it every time you discover a better way to do something. You'll reference it daily at first, then weekly, then occasionally, but you'll never stop finding it useful.

Here's a starter template:

# DAILY SETUP
cd ~/projects/docs
git fetch --all --prune
git pull origin main

# STARTING NEW WORK
git checkout main
git pull origin main
git checkout -b js-descriptive-name

# WORKING ON FEATURE BRANCH
git add .
git commit -m "[TICKET-123] Brief description of change"
git push origin js-branch-name

# SYNCING YOUR BRANCH WITH LATEST MAIN
git checkout js-your-branch
git fetch origin main
git merge origin/main
# resolve any conflicts, then:
git add .
git commit -m "Merge main into feature branch"

# AFTER PR IS MERGED
git checkout main
git pull origin main
git branch -d js-merged-branch
git push origin --delete js-merged-branch

# OH SHIT COMMANDS
git reflog                        # Find lost commits
git stash                         # Quick-save changes
git stash pop                     # Restore stashed changes
git reset --hard origin/main      # Nuclear option - start over
git log --oneline --graph         # Visualize history

Automate your morning routine

Identify the commands you type every single morning and put them in a script.

Mine looked like this:

cd ~/cloud-desktop
bash daily.sh

That script handled authentication, workspace sync, and pulling changes from remote. Five minutes of setup work that saved me from forgetting critical steps every morning. You can find a sample script here.

The five rules of Git hygiene

These practices came from years of collective experience across our teams at AWS. Some learned from writers who'd been doing docs-as-code for decades, others from painful mistakes we made along the way. We documented them on our team wiki as onboarding material. New hires could read them before their first commit. We reinforced them in team meetings and 1-on-1s. Eventually, they became part of org-wide standardization.

They also prevent disasters.

1. Never commit directly to main

Always work on feature branches. Main should only receive changes through merged pull requests that have been reviewed.

This single rule prevents most catastrophic mistakes. If you find yourself in this pickle, here's how to get out.

## I committed to main instead of my feature branch (NOT pushed yet)

git branch js-feature-name        # While on main, make a copy of main with your commits
git reset --hard origin/main      # Reset main to match remote
git checkout js-feature-name      # Switch to your backed up branch
git push origin js-feature-name   # Push your new branch to remote and continue working

## I committed to main AND pushed to origin (don't panic!)

1. Alert your team immediately in Slack/chat
2. Check if anyone has pulled: ask in chat before doing anything
3. If NO ONE has pulled yet, you can safely undo:
   git checkout main
   git reset --hard HEAD~1        # Remove your commit locally
   git push origin main --force   # Update remote (ONLY if no one pulled!)
   git checkout -b js-feature-name
   git cherry-pick <commit-hash>  # Bring your work to the feature branch
   
4. If someone HAS pulled, use revert instead:
   git checkout main
   git revert HEAD                # Creates new commit that undoes changes
   git push origin main
   git checkout -b js-feature-name
   git cherry-pick <commit-hash>  # Bring your original work to feature branch

# Use `git log` or `git reflog` to find the commit hash you want

2. Pull frequently, push infrequently

Always be pulling from remote and merging into your feature branches. Do this at least weekly for idle branches. Do it throughout the day for active work.

The more often you pull and merge, the less likely you are to face massive conflicts.

Why this matters: I once worked with a writer who let branches go stale for weeks. When merge conflicts appeared, they'd panic and blindly accept their changes over everyone else's. They deleted entire pages of content written by other team members. We worked extensively to build better habits, but when the same data loss happened again months later, we had to part ways.

3. Resolve conflicts carefully

When you see conflict markers in your file, stop and think:

<<<<<<< HEAD (your changes)
Configure IAM roles before enabling encryption.
=======
Enable encryption first, then configure IAM roles.
>>>>>>> main (their changes)

Don't just delete one side. Ask yourself:

• What was I trying to accomplish?
• What were they trying to accomplish?
• Which version is technically correct?
• Do both changes need to coexist somehow?

When in doubt, talk to the other writer before resolving the conflict. Five minutes of conversation prevents hours of recovery work.

After resolving conflicts manually in your editor:

git add .
git commit -m "Resolve merge conflict in security-setup.md"

4. Follow the pull request workflow

The typical docs-as-code workflow looks like this:

Create your feature branch:

git checkout main
git pull origin main
git checkout -b js-new-feature

Do your work, commit frequently:

git add .
git commit -m "[DOC-1234] Add security configuration guide"
git push origin js-new-feature

Open a pull request. If you're working with PRs, write a clear description of what changed and why.

Address review feedback:

# Make requested changes
git add .
git commit -m "Address review feedback - clarify IAM setup"
git push origin js-new-feature

# PR automatically updates with new commits

After approval, merge. Most teams use "Squash and merge" or "Create a merge commit" depending on their preferences.

Clean up immediately:

git checkout main
git pull origin main
git branch -d js-new-feature
git push origin --delete js-new-feature

5. Write searchable commit messages

You will need to find that update that you made six months ago. Someone will ask "why did you make this change?"

Be specific. Use words you can see yourself searching for later. Include ticket numbers.

Good commit messages:

• [DOC-1234] Add troubleshooting guide for encryption errors
• Fix broken links in security setup guide
• Update IAM role examples to use new policy format per security team review

Bad commit messages:

• changes for Joe
• fix stuff
• Ready for review

This is why I never adopted rebase. The argument for rebase is cleaner history (linear commits instead of merge noise). But I like that merge noise. I want to see the minutiae of commit history. Why take the time to write meaningful commit messages if you're going to squash them into some sanitized version of what actually happened?

Small commits, clear names, quick cleanup

Commit often. Finished a section? Reorganized a list? Commit. Small commits keep messages concise and meaningful. They reduce merge conflict probability.

Name branches well. Prefix with your initials. Use consistent conventions:

• Ticket numbers: js-DOC1234
• Plain language: js-security-access-control
• Hybrid: js-DOC1234-security-access-control

Delete merged branches immediately. Stale branches clutter your workspace, trick you into thinking work is still in progress, and cause you to accidentally branch from the wrong starting point.

It becomes muscle memory

Once you get into a rhythm that works, these habits become automatic. They prevented data loss on my teams. They kept commit history complete. They made collaboration smoother.

The perfect workflow is the one you'll actually follow consistently.

The learning curve is real

This probably feels like a lot on day one. Save it somewhere. Re-read it periodically. It will keep making more sense.

The transition from a traditional CMS to docs-as-code requires a mindset shift. You're not just a writer anymore. Now you're managing version control, handling merge conflicts, thinking about how your change history will read six months from now. Your decisions affect everyone working in the same repository.

But once these habits become muscle memory, you'll wonder how you ever worked any other way.

Just don't let your branches go stale.

Sample startup script

Save this as ~/daily-git-setup.sh and run it each morning:

#!/bin/bash
# Daily Git setup script for technical writers

GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

echo -e "${GREEN}Starting daily Git setup...${NC}\n"

# Navigate to your docs repository
cd ~/projects/docs || exit 1

echo -e "${YELLOW}Fetching latest changes...${NC}"
git fetch --all --prune

echo -e "${YELLOW}Current branch:${NC}"
git branch --show-current

echo -e "${YELLOW}Cleaning up merged branches...${NC}"
git branch --merged main | grep -v "main" | xargs -r git branch -d

echo -e "${YELLOW}Your active branches:${NC}"
git branch | grep "js-" || echo "No active branches found"

echo -e "\n${GREEN}Setup complete!${NC}"

Make it executable: chmod +x ~/daily-git-setup.sh

Customize the cd path and the grep "js-" to match your initials.

(Optional) Create an alias in your shell config:

Add this line to your ~/.bashrc or ~/.zshrc:

alias gitdaily="~/daily-git-setup.sh"

Then you can just type:

gitdaily

Have Git hygiene practices that saved you? I'd love to hear them. These are the habits that worked for me and my teams, but every environment teaches you something new.

Spreadsheets fall apart when you're tracking a million applications across different stages, each with its own requirements and contacts. I needed something better, so I built it. I used AI, iterative refinement, and a focus on what job seekers like me actually need.

⚠️ Important: This app stores everything locally in your browser. The Back Up button lights up as a reminder. Use it regularly; if you clear your cache or switch browsers, your data disappears.

Try it now! https://jburgh.github.io/job-search-dashboard

Jump to What it does and How to use it.

Why I built it

I was tracking applications across Gmail confirmations, Google Drive file creation dates, and LinkedIn's "Applied" indicator. It was chaos.

I'd get rejection emails for jobs I couldn't remember applying to. I'd get callbacks and scramble through Google Drive trying to figure out which resume version I'd sent. I'd accidentally apply twice to the same role because I had no central record.

I needed something that could:

• Track every application in one place
• Show me which roles were still on the radar, which roles I'm actively engaged with, and which ones I can forget about
• Give me one-click access to careers pages
• Bubble up the companies that I should be checking every day
• Capture links to the resume, cover letter, and job URL
• Show me how far I was getting with the roles where I broke through
• Back up my data so I didn't lose everything
• Be easy to update on the fly

How I built it

I'm a technical writer, not a software developer. I can read code and write scripts, but building production web apps isn't my specialty. AI changed that equation.

Phase 1: Rapid prototyping with Claude

I started with a simple request: "Create a job tracking system with target companies, application tracking, and localStorage persistence." Claude generated a working React application with companies and jobs tables with filtering and basic stats. It worked, but it was rough around the edges.

Phase 2: Iterative refinement

I refined the prompt to add features like one-click Careers page access, application status tracking, and backup/restore functionality. Each time, I fed Claude the existing code and asked for specific improvements.

Each iteration took minutes. Describe the problem or specific need, get a solution, test it, refine. This is AI-assisted development. You need domain expertise, but not necessarily implementation expertise.

At this point, I ran a Google Takeout export of my Drive and email correspondence. I asked Claude to parse the data for cover letters or confirmations/rejections and use the date metadata to generate an importable JSON file of my job application history.

I started using the dashboard app daily, and it was already making a difference in my job search. Hosted on my local machine, I could make tweaks in real time when a new idea struck me. (It's also when I prompted Claude to make it pretty.)

Phase 3: Production hardening with GitHub Copilot

So... success! Right? Well not quite. All the iterations had made for a pretty messy codebase. I needed to clean up, optimize, and ensure the app was robust enough for regular use.

I moved the code to VS Code and used GitHub Copilot to transform the prototype into production-ready code through multi-stage refinement:

• Code Quality Audit: "Act as a senior engineer reviewing this code. Identify code smells, duplication, and areas that violate DRY principles. Suggest refactoring strategies."
• Security Hardening: "Act as a security engineer. Review this code for XSS vulnerabilities, injection risks, and unsafe practices. Implement proper input sanitization and validation."
• Performance Optimization: "Act as a performance engineer. Identify bottlenecks, inefficient algorithms, and unnecessary re-renders. Optimize for scalability and responsiveness."
• Production Deployment: "Generate deployment scripts and configuration for hosting this as a static site on GitHub Pages. Include build optimization and error handling."

This multi-stage approach of rapid prototyping with conversational AI, then hardening with code-focused AI, transformed my modest tracker into a robust application.

What it does

Company inventory

This view is most useful for remembering which companies you should be checking for new roles to drop. In V1, I pre-loaded some companies with direct links to their job search pages. You can hide these from view if they're not useful in your search.

Click a company name to visit their careers site. Click the application count to filter your jobs view to that company. Add new companies manually or let them auto-generate when you add jobs.

💡 Pro tip! When you've applied your preferred filters to a Careers page search, copy that URL into the tracker so that future visits take you directly to the results you need.

Application tracking (jobs)

This is the heart of the app. Here you track each job application from submission to response.

Core workflow:

1. Browse Companies → Click careers link → Find role
2. Add Job → Fill in company, title, date, URL fields
3. Update Status and Progression as you move through the pipeline
4. Close with appropriate reason and the closing date when done

Data structure for job statuses:

• Applied: Submitted, waiting for response
• In Progress: Active conversation
  • Progression: Recruiter Screen → Partial Loop → Full Loop → Offer
• Closed: This role is no longer active or you've eliminated it
  • Close Reason: Rejected, Ghosted, Withdrew, Declined Offer

With this structure, we get some useful analytics. Response rate measures jobs that moved beyond "Applied." Pipeline health shows distribution across interview stages. Closure patterns reveal whether you're getting rejected, ghosted, or withdrawing.

Data management

This is a critical feature: One-click JSON export for backups. The backup button turns red as a reminder to use it regularly. Since all your data is hosted locally, you don't want to risk losing it all when you clear your cache or switch browsers.

If you do blast away your data, simply import your latest backup to restore. Keep in mind that the app is intended for desktop use and you won't be able to see your inputs on another device (like your phone) pointing to the same URL.

How to use it

The dashboard is live and ready for you to use at https://jburgh.github.io/job-search-dashboard.

⚠️ Important: Data is stored in your browser's localStorage. It will disappear if you clear your cache. The Backup button at the top turns red every day or so as a reminder. Use it to export your data to an importable JSON file.

Companies Tab

I've preloaded some companies for convenience. You can hide any with the Hide button, or add your own.

• Select a company name to navigate to its career page
• Select the application count to filter your jobs view to that company
• Select "Add Company" to enter new companies manually

Jobs Tab

Select "Add Job" to log each application. When you add a job, the tracker looks for the company name and automatically relates the job to the company in the tracker. If the company isn't tracked yet, the app will create it for you. You'll want to update the company URL later, because it defaults to the job URL that you enter with the application.

As you progress:

• Set status to "In Progress" when a company reaches out (even just a recruiter screen)
• Update Progression as you move through interview stages
• Set status to "Closed" and choose a Close Reason when you get a rejection, withdraw, or are eliminated
• Set the Follow-up date to the date you got rejected or withdrew

Best Practices

• Add jobs immediately after applying (before you forget details)
• Capture contact names when recruiters reach out
• Write notes after each interaction
• Set priority tiers honestly (don't mark everything Tier 1)
• Back up daily - seriously, make this a habit
• Review analytics weekly to adjust your strategy

Why I'm sharing it

Job searching is hard enough without fighting your tools. You shouldn't need a CS degree to track applications effectively. You shouldn't have to choose between spreadsheets that are too simple and enterprise systems that are too complex or expensive.

So I built this. And now it's yours. Use it, share it, modify it.

If this helps even one person organize their search better or land a role faster, it was worth building (especially if that person is me!).

And seriously, back up your data. You'll thank me later.

Try the dashboard: https://jburgh.github.io/job-search-dashboard

Built by a job seeker, for job seekers, shared freely.

Questions or suggestions? Find me on LinkedIn or check out my portfolio.

If your portfolio only shows writing samples without the So what?, you're positioning yourself as just a writer. The work you do has bigger impact than that. Let's make sure your portfolio shows it.

• Do your project titles describe the problems you solved?
• Can someone outside your role understand why each project matters?
• Do you reflect on the impact, outcomes, and tradeoffs for each project?
• Do the same strengths show up consistently throughout the portfolio?
• Could a reader imagine how your experiences might apply to any role?

More than one No? Your portfolio might be working against you.

The portfolio paradox

I've rebuilt my portfolio three times in the past five years. Each time, I thought I was being thorough and professional. Each time, I was accidentally narrowing how hiring managers saw me. Like mine, most portfolios are built with good intentions. They document our experience and prove we've done the work. And that creates the problem.

By focusing so carefully on what we have done (our past roles, titles, and responsibilities), we guide readers toward a single, overly specific version of us.

What pigeonholing looks like (and why it happens)

You've spent years building your career. You're really good at what you do. That experience shows up in your portfolio: the roles you've held, the products you've worked on, the skills you've honed over time. But that clarity is why pigeonholing happens.

When you list "Senior Technical Writer," "API Documentation," and "Developer Guides," people see one thing: a technical writer. They can't imagine you leading a content strategy initiative, reducing support case volume, or improving product design and direction.

When you're competing for roles during a tight job market, every application needs to work harder. A portfolio that positions you for exactly one type of role is a liability that you can't afford.

Reframing your portfolio around problems, not positions

Most portfolios default to chronological order or group by deliverable type. Both organize around you, not around problems you solve. This limits how others imagine you'd apply those skills in a new context. Start with a simple shift in perspective. Instead of thinking, "Here's the role or project," think, "Here's the problem that I helped solve."

Choose to organize your projects by user problems, business outcomes, complexity, scale, or maturity stage. Use summary-style titles that translate across roles.

This framing immediately broadens the story. You're describing the same work, but the value becomes clearer to a wider audience. Engineering leaders, product managers, and platform teams all recognize onboarding friction as a real problem. Now you've offered context rather than a headline. Judgment, decision-making, and impact carry across roles far more easily than a project name or job title.

Making your portfolio flexible without making it vague

I know what you're thinking. If you stop anchoring your portfolio to a single role, you're going to seem scattered or unfocused.

Trust me... clarity comes from repetition. When the same strengths pop up across different projects, readers recognize patterns. They see how you approach complexity, advocate for users, and help teams scale. You can accomplish this without risking ambiguity:

• Add short summaries at the top of each project that explain why the work mattered.
• Emphasize outcomes, constraints, and tradeoffs.
• Use consistent language to describe your strengths across projects.

This approach also improves usability. Readers can skim, search, and focus on the work that feels most relevant to them, rather than trying to infer your range based on titles alone.

Using AI to reframe your work

AI tools can be genuinely useful when you are revisiting how you frame your experience. They are particularly good at generating alternative perspectives. You can ask them to rewrite a project description for different audiences, surface transferable skills you may be underemphasizing, or suggest adjacent roles that your experience could map to. Used this way, AI helps you explore options and spot patterns.

I used Claude to reframe my own portfolio. I asked it to rewrite each project description for three different audiences: content strategists, technical program managers, and executive-level product managers. The exercise revealed patterns I'd been too close to see. But Claude couldn't tell me which framing was most authentic to my actual strengths. Only I could make that call.

The important part is authorship. AI can assist with exploration, but the final framing still depends on your judgment, priorities, and voice.

Portfolios as living systems

Portfolios reflect how you want to be understood at a particular point in time. As your goals evolve, your portfolio should evolve alongside them. When you revisit your portfolio and the way you frame your work, it signals that your career is moving forward.

I'm rebuilding mine right now. Not because I don't know what I've done. I know that cold. But because I understand that what I've done isn't the same as what I can do next.

Ask someone outside your role what they think you do after skimming your site for two minutes. If the answer is, "You write documentation," then you might be presenting all you do too narrowly. A few small adjustments can turn your portfolio into a tool that creates more options for your future.

This post is part of Per the docs, a monthly collaborative series where technical writers explore different aspects of our craft. Each month features a new topic with perspectives from writers across the community. Read more perspectives in the series:

January 2026 topic: Portfolios

• Brandi Hopkins - Story and Structure: Building a modern technical writing portfolio
• Shelby White - Portfolio refresh

View all participants in this month's hop →

I've spent most of my career thinking about content as infrastructure. Not as output, but as the thing that supports systems at scale. How people learn, how teams onboard, how products get understood, and how organizations move faster (or don't!).

When content works, it's invisible. When it doesn't, everything feels harder than it should.

This blog explores that idea, along with two related threads: documentation tools keep evolving, and how careers in content evolve alongside them.

Tools matter. I've worked with generations of doc platforms, each promising to make content easier to create and maintain. AI-powered tools are changing that landscape again, raising questions about authorship, quality, ownership, and trust. I'm less interested in hype than in how the tools actually fit into sustainable content systems.

Careers matter too. Content roles are rarely linear. The way we frame our work shapes the opportunities available to us. I'm interested in how people grow in this space, how they avoid narrow definitions, how they position experience as tools shift, and how they build careers that adapt.

If you work in documentation, content strategy, developer experience, or any role where clarity supports scale, I hope something here is useful, or at least helps you see familiar problems from a different angle.

Thanks for reading, and... docs, or it didn't happen!