Christian F. Rojas
ENES
All cases

Case 02

A change-plan method for documentation, in production across three releases

Change requests reached us as emails, tickets and version diffs thousands of lines long. I turned them into a versioned, traceable method and applied it to three product releases.

115
changes traced across 3 releases (43 + 56 + 16)
54
questions for subject-matter experts
27 · 14
Jira stories traced and reviewer comments incorporated
System diagram: traceability and escalation in the change-plan methodEvery item is traced in both directions along the chain verbatim quote, REQ, CH, P. When sources disagree, the contradiction goes to a contradiction log, highlighted, and is escalated, not settled on my own criteria. The method is in production: 3 releases, 115 changes traced.verbatim quoteREQCHPcontradiction logescalatednot settled by metraced both wayssources disagreein production · 3 releases · 115 changes tracedSystem diagram: traceability and escalation in the change-plan methodEvery item is traced in both directions along the chain verbatim quote, REQ, CH, P. When sources disagree, the contradiction goes to a contradiction log, highlighted, and is escalated, not settled on my own criteria. The method is in production: 3 releases, 115 changes traced.verbatim quoteREQCHPcontradiction logescalatednot settled by metraced both wayssources disagree3 releases · 115 changes
Fig. 02 · System diagram

My decisions 04

  • Set the method's hard rules, including "nothing is discarded silently".
  • Remove effort estimates from the deliverables, because I could not justify how they were measured.
  • Split the deliverables by audience: an approval one-pager for the PM and an execution guide for the writer.
  • Adopt GitHub as the versioned source of truth and the shared dashboard as the live visual layer.

Assisted execution 02

  • Claude Code indexed the manuals with parallel sub-agents and drafted each plan under the method's rules.
  • Claude Code built the self-saving HTML one-pager and generated the Word execution guides.

Context

I lead technical documentation for a line of fraud-prevention products in enterprise cybersecurity. Change requests arrived without structure: emails, Jira stories and diffs between manual versions that ran to thousands of lines. Each release meant rebuilding the same reasoning from scratch.

What I decided

I turned the work into a reusable method, and every correction I made while using it became a rule. Some of those corrections:

  • No effort estimates. I removed them from the deliverables. My reason at the time: I did not know how they were measured, and I had no way to justify them.
  • The approver sees content only. The one-pager shows content changes. Editorial changes and file handling go only to the writer’s guide.
  • Engineering’s draft is input, not finished work. Content that Engineering had already written into the new manuals is processed like any other source. That reclassified 5 changes.
  • Nothing moves once published. A change is never deleted and a published ID never moves. The state saved from the live dashboard prevails over the plan.

When several people needed to edit the tracking dashboard, I chose a hybrid model: GitHub as the versioned source of truth, the shared dashboard as the live visual layer.

How it works

  • Inputs and rules. Four inputs (the base version, the target version, the request pasted unedited, and context) and ten hard rules. Among them: never invent technical content, quote verbatim, anchor every change to file, section and line, and separate requested changes from derived ones.
  • Six phases. Validation, indexing with parallel sub-agents, structuring the request into atomic requirements and changes, impact and propagation, gaps and risks, and deliverables.
  • A full trace chain. Quote → requirement (REQ) → change (CH) → open question (P), with separate IDs for contradictions and reviewer comments.
  • A three-axis taxonomy. Type (added, modified, removed), class (content, editorial) and status (ready, pending technical validation, blocked). A blocked change always says what is missing and who must provide it.
  • A ten-point closing check. Contiguous IDs, counts computed and never typed by hand, accents and WCAG contrast.
  • Two deliverables for two audiences. An HTML approval one-pager for the PM, with a self-saving tracking dashboard and comments; and a Word execution guide for the writer, with one card per change, expert questions and a QA checklist.

The most quotable rule: “nothing is discarded silently.”

What it produced

Version 2 of the method came out of real use on two products. It was applied to three releases:

  • Product A, vN → vN+1. 6 manuals compared, 43 changes, 27 expert questions and 27 Jira stories traced. The team saved the live dashboard and moved changes to ready.
  • Product B, vN → vN+1. 56 changes across 86 tracking units, 27 expert questions and 14 reviewer comments incorporated into the plan.
  • Product A’s mobile SDK, vN → vN+1. 16 content changes and 3 broken links found in the change analysis; a separate bilingual QA pass found 3 gaps.

Both products now share the same dashboard and guide format.

What it does not prove yet

I have not measured hours per plan before and after the method. I also have no count of changes that reached the release without rework, or of blocked changes resolved before the release. The method is in use; its efficiency is not yet proven.

What I would do next

Log the hours per plan for the next releases and compare them with the earlier ad hoc approach. Track how many blocked changes are resolved before each release, using the dashboard the team already keeps.