AI As A Technical Writer: Amazing Results

AI
1

A recent UI revamp of my site meant moving the "how to's" from the top of each feature page, to a centralized Documentation section. This was an intentional design decision, not something forced upon the site because of the new UI. As I get more and more comfortable with Claude Code, I decided to let it write the documentation.

My first attempt wasn't great. I just told it to scan the site and create the documentation. Never having written documentation myself, or holding a technical writer position, I didn't craft a very good prompt. I was unimpressed with AI's result.

My second attempt involved using multiple agents (Agent Teams) and specifically asking for several different agent types: lead (default behavior for Claude's Agent Teams), a technical writer, a UI designer, and an industry/domain expert in the music business, working together to create the documentation. The prompt gave more context for each role than just naming them. I'm just trying to limit the length of this post. :slight_smile:

The result was incredible to watch as I asked Claude to complete one section for me to review (I wanted to see if it was worthwhile continuing). Claude started by spinning up the industry expert agent, doing research that would specifically capture how musical artists and their management teams use today's tools and platforms for all things related to artist management. That research then fed the technical writer agent, guiding it on why this feature on my site is valuable to the intended audience (artists, management). The technical writer was also asked to create charts, tables, call outs, mini how to's, etc., improving the usefulness of the documentation itself. Then the UI designer took the work of the domain expert and technical writer, built the UI and fed in the copy. It took a few minutes but what I saw when it completed was amazing. Claude was ready to continue with the rest of the sections and I quickly said, "YES!".

The lead agent then proceeded to start up several domain experts and technical writers, each paired and taking on a specific section. The lead agent decided it was best to work on two sections at a time. When the 2 agent team was complete, I'd see the UI designer agent fire up and start building the section. The whole process took roughly 20 minutes and I'm extremely happy with the result. Yes, I'm having to read, review, and revise a little here and there, but I'll gladly do this.

Moving from a single agent, whether it be Google AI Studio (where I started) or Claude Code's default single agent approach, to Agent Teams (still considered beta by Anthropic) is yet another "game changing" event in AI history.

Happy to answer any questions about my process or set up.

2 Likes
2

I just had to update some of the documentation based on a feature I added this morning. If you haven't seen Claude Code in action, here's a snippet of what it did. My prompt is first, then Claude keeping me informed about what it was doing.

*We now need to update the Documentation for this new section in Audience Insights. As before, please use Agent Teams to complete this task. Create a music industry expert with domain expertise on the tools and workflows bands and their social and marketing teams use, a technical writer agent, and a UI designer. Follow the existing Documentation style to now update Audience Insights to specify that it has two sections (one for pages, one for links), and answer the why/what/how for the new Page Traffic Insights section of the page. *

:record_button: Let me read the docs page first to understand the existing structure before spinning up the team.

:record_button: Read 1 file (ctrl+o to expand)

:record_button: Good. I have everything I need: the full existing docs section for Audience Insights (lines 652–754), the CSS classes, callout types, and the actual PTI UI components. Setting up the team now.

:record_button: Now set up the dependency (Task 3 blocked by Tasks 1 and 2) and spawn all three agents — experts in parallel, writer waits:

:record_button: 2 agents launched (ctrl+o to expand)
├─ @music-expert
│ ⎿ Music industry expert brief (↓ to manage)
└─ @ui-designer
⎿ UI designer structure outline (↓ to manage)

:record_button: Music expert and UI designer are running in parallel. Waiting for their briefs to come in — the technical writer will be spawned once both are complete.

@ui-designer❯ UI structure outline for Page Traffic Insights docs sub-section

:record_button: The UI designer's outline has some structural misunderstandings I'll need to correct for the tech writer — it treats Page Traffic Insights as a third tab, but it's actually a section within the
FanLinks Analytics tab, and it lists incorrect card names. I'll flag this when the music expert is done. Let me check status.

:record_button: Task #1 is marked complete — the music expert's message must be in the queue. Waiting a moment for it to arrive.

@music-expert❯ Task 1 complete — music industry brief ready

:record_button: Both briefs are in. Let me mark Task #2 complete and spawn the tech writer with full corrective context.

:record_button: Task(Tech writer updates Audience Insights docs)

:record_button: Tech writer is running with full corrective context. It will update only the #audience-insights section — keeping all existing content and inserting the new Page Traffic Insights block in the
right place (as a section within FanLinks Analytics, not a new tab). I'll let you know when it's done.

@ui-designer❯ Updated structure outline — Page Traffic Insights within FanLinks Analytics

:record_button: The UI designer's revised outline is excellent and aligns perfectly with the corrections I already gave the tech writer. Let me forward it to reinforce the key structural decisions — especially
moving the "QR scans" callout up into PTI and removing it from the bottom.

:record_button: The tech writer has the complete, corrected brief. Waiting for them to finish writing and editing the file.

@tech-writer❯ Task 3 complete — Audience Insights docs updated

1 Like
3

When it's done, it knows to pause to allow me to review and provide feedback. I can ask it to make corrections or say "approved and commit" which tells Claude to commit the files to my github with a title and description of the changes.

2 Likes