1. I'd Rather Be Writing
2. AI
3. Agent skills

Roles for tech writers with product skills

In enterprise documentation pipelines, there’s a lot of detail and technical know-how required in each stage of context engineering. You could even dedicate entirely different teams to each stage of the lifecycle:

• Generating the skills
• Deploying the skills
• Generating tests for the skills
• Running the tests and evaluations
• Identifying areas for improvement
• Making the improvements to the skills
• Making improvements to the content

What role should technical writers play in context engineering? Keep in mind that technical writers are doing these tasks on top of their existing content development and maintenance roles, which have often become more burdensome due to thinned resources.

Getting involved in skill creation

Although it’s easiest to delegate the creation of skills to an automated product skill creator, as the SkillsBench study found, AI-generated skills often lack the context and domain awareness of human experts who can shape, curate, and direct the skills to be much more effective. Skills themselves are quick reference guides to documentation; in other words, they’re a documentation artifact and should be owned and generated by the people who know the documentation better than anyone else.

Why tech writers should own skills for the products they support

Here’s why tech writers should own product skills:

• Tech writers know the product’s capabilities.
• Tech writers know where each capability is described in the documentation.
• Tech writers can assess whether a test’s questions and tasks are well suited to the product.
• Tech writers can assess whether the answers an agent provides to a test align with the documentation’s answers.

Also note that the skill isn’t a deep dive into any of the product’s capabilities, tasks, or information. The skill is high-level and mostly routes to the correct place in the documentation. As I said in the anatomy discussion, a product skill is essentially a quick reference guide for machines, and quick reference guides are a genre tech writers already own. I wrote a whole series on them years ago, starting with Quick Reference Guides: The Poetry of Technical Writing back in 2008. The constraints that make a good QRG (radical compression, knowing what to leave out, organizing for lookup rather than reading) are the same constraints that make a good product skill. As such, the tech writer is perfectly suited to own the skills for the products they support.

A tech writer can use a product skill creator to generate a basic skill, and then look at the output and shape, refine, curate, and adjust the skill as needed to align with a good outcome. Tech writers often don’t play a more critical role in skills development for the following reasons:

• The skill’s format and structure is often unfamiliar.
• The test case format and structure is even more unfamiliar.
• Understanding how to run the test cases using the company’s testing framework seems to align more with the QA role.
• Massive numbers of skills need to be generated seemingly all at once.
• It’s unclear how tech writers should take action on low-performing eval scores. Is the test bad? Is the content poor?
• There doesn’t seem to be a clear publishing destination for skills within an existing documentation site, so it doesn’t seem to fit or be relevant there.
• Tech writers have been trained to write for human users, not agents. Even analytics don’t distinguish between human users and agents, so it’s hard for tech writers to recognize the true audience using their documentation.

Meanwhile, most tech writers are already buried under a mountain of doc requests and issues in their backlog. When you add an additional set of unfamiliar requirements, it can be overwhelming.

Investment in the eval loop

Another reason tech writers should be more involved in skill creation is because it will give them more investment in action items from the eval loop.

As soon as we start testing our skills, one outcome will be to improve the skill’s score on the tests. If the skill scores poorly on some task that is identified in the product skill, and the evaluation recommendation is to improve some part of the documentation to raise the agent’s performance on the task, the tech writer will be much more invested in actually taking action on the recommended improvement if they’re the ones trying to actively raise the scores.

In contrast, if an engineering or evaluation team generates an automated pull request (PR) or code change for the tech writer without prior context, it can seem to arrive out of nowhere without a clear sense of user friction, identified error, release change, or other reason. It will simply be a proposed change that materializes out of thin air, with no requester, no audience, and no purpose. In automated documentation pipelines — where machine workflows can propose large volumes of documentation fixes daily — writers need hands-on involvement in evaluation loops to act as effective validation leads and content architects.

Roadmap for technical writers

As part of the expectations for technical writers, tech writers should meet the following requirements:

• Provide a skill for each product supported.
• Provide tests for each skill.
• Run the tests on a regular basis and report the metrics.

A dedicated team should still provide the meta skill for all teams — that is, a skill-creator skill that generates product skills, encoding the organization’s template, conventions, and quality bar so that individual writers aren’t reinventing the structure. However, the tech writers should be the ones running that meta-creation skill against their own products, then curating and refining what it produces.

---

Continue to the next topic: Mining users’ AI chat sessions: gaps and forensics

Comment on LinkedIn