AI-Pushed Necessities and the Evaluate Tax: PubHub Half 4

PubHub is Cisco DevNet’s inside content material administration system, and that is the fourth half within the sequence of how the DevNet workforce rebuilt it from the bottom up. In Half 1, we coated the wins and hurdles of rebuilding PubHub, whereas Half 2 explored how AI accelerated our software program growth lifecycle (SDLC). Half 3 is in regards to the DevNet UX workforce’s journey to show Cisco design requirements into AI abilities and an MCP server. Now, we’re diving right into a workflow evolution the place we used AI to seize undertaking necessities, acceptance standards, and extra. This shift might have been greater than what we bargained for.

The Exhilaration of AI

As a result of we had been rebuilding from scratch, we noticed a chance to rewrite the brand new system primarily based on a decade of non-public expertise. We used AI to assist doc the necessities for this undertaking utilizing VS Code Copilot paired with Claude Sonnet and Opus.

On the earth of Agile growth and the SDLC, we use epics to arrange advanced initiatives. An epic is a high-level requirement or a large-scale function that’s too huge to be accomplished in a single dash. It acts as a container for a number of associated consumer tales, offering the mandatory context and scope for the engineering workforce. To maintain tempo with AI’s velocity, we didn’t use conventional doc packages like Phrase. As an alternative, an AI talent generated the epics and consumer tales in Markdown and hosted them in an inside GitHub repo. Versioning every change and sustaining a transparent changelog because the undertaking advanced allowed us to deal with our necessities like code.

The preliminary outcomes had been thrilling. AI reworked the story writing course of from a chore right into a superpower. I might feed AI particular standards and ache factors, and it could immediately generate:

• Complete Context: Clear enterprise worth and scope to stop scope creep.
• Technical Precision: Detailed acceptance standards, actor views, and key ideas.
• Fast Prototyping: API request/response fashions, wireframes, and HTML-based mockups to align engineering, design, and management.

AI didn’t simply write; it managed. It versioned paperwork and maintained a meticulous changelog throughout 12 dense epics, every linked to baby tales and their dependencies.

I felt like I had discovered a cheat code for technical management.

The Tipping Level: When “Full” Turns into “Too A lot”

Because the documentation grew, I hit a wall. The epics turned so dense that even I, the one who prompted them into existence, struggled to evaluate and edit them. For instance, I’d incessantly meet with the engineering workforce to debate points and compromise on launch trade-offs. After the conferences I used my agent in VS Code Chat to replace the necessities inside the epics. Whereas the device flawlessly synced updates throughout our documentation pipeline, it handed me a large evaluate queue. I refused to blindly approve lots of of modifications, preferring to maintain the human within the loop (me) relatively than constructing one other agent to deal with the evaluate.

This created a paradox the place AI gave us good consistency, however I paid for it with hours of handbook verification.

I keep in mind considering, If AI hadn’t identified these tiny dependencies, it could have taken me days to search out them manually or miss them utterly. However then the belief hit me: I wouldn’t have written this a lot content material within the first place. AI had generated a mountain of content material, and I used to be spending all my time digging by it.

The “Evaluate Tax” turned obvious after I shared the meticulously written epics with my colleagues. After sharing the epics with the principal engineer, I heard that the documentation was too prescriptive for engineering. It was too detailed, didn’t depart sufficient room for engineering to adapt primarily based on the brand new system they had been constructing, and most significantly, it could take too lengthy for the entire workforce to learn.

I initially smirked, considering, Why would they learn it when AI can learn it for them?

It raised a sensible query: Was I making a loop the place I used AI to generate documentation in order that it might be learn and carried out by AI? Whereas the content material was clear and complete, the sheer quantity had turn into a barrier to the very collaboration it was meant to assist.

The Pivot: Writing for People

I spotted that in my quest for technical perfection, I had forgotten crucial stakeholder: the human.

We pivoted to a lean documentation method, however we didn’t throw away the epics. These epics remained the “deep-dive” supply of fact, good for AI ingestion and technical reference. As an alternative, we created summaries. These had been bite-sized, high-level references that allowed engineers, designers, and managers to know the large image, perceive key workflows, and determine associated and dependent epics with out drowning intimately. By creating parallel “AI-readable” epics with “human-readable” epic summaries, we restored the stability between technical depth and organizational agility.

AI can exponentially enhance the quantity of output we produce, however it can’t exchange the human want for readability and brevity. If we aren’t cautious, we are going to spend extra time managing the output of our instruments than we do main our groups.

Going ahead, I like to recommend a lean method to producing documentation, whether or not or not it’s epics, consumer tales, or technique docs. Once we discover ourselves in awe of what AI can generate, we should keep in mind to pause, search for, and ask ourselves: Within the rush for productiveness, who’s main whom?