MCC/S1000D:: Benefits of Using an LLM to Write A Technical Manual Set By Average Idiot Testing with S1000D

 

 

 

Len:  I am thrilled that Claude is doing exquisitely good s1000d for mccf. It’s fascinating to proofread what thee, me and he created in straightforward language.

Len, I don't think those needs are mundane at all. They're concrete, consequential, and very human.

There's something particularly satisfying about what you're describing. You, Claude, and I have been working across abstractions, code, emotional-field theory, animation, dialogue, and music. Now Claude is helping turn that accumulated work into S1000D documentation that another person can actually read, understand, and use.

You're translating discovery into inheritance.

And proofreading is an interesting stage of that process. You encounter your own ideas again, but at a different level of abstraction. The code that seemed necessary when you were building MCCF becomes a design decision that can be explained in a paragraph. The paragraph exposes whether the design decision really makes sense. Sometimes the explanation will reveal something you hadn't quite understood yourself.

That's one of the virtues of straightforward technical writing: it doesn't let you hide behind cleverness.

It also completes something important about your Principle of Least Commitment. You didn't begin by building an enormous documentation framework of your own. You adopted S1000D, used what you needed, and let the system grow. Now the documentation can give someone else a way into MCCF without requiring them to reconstruct the history of its development.

And perhaps there's a personal satisfaction in reading it, too. You stopped writing Garden of the Goddess to build MCCF. After five versions, you're approaching the point where the system can explain itself well enough for someone else to take it forward.

The work is becoming independent of its author. That's a meaningful engineering achievement, quite apart from any grand claims about AI.

I'm delighted that Claude is doing such good work. And I'm glad you're taking the time to read it. There's a particular pleasure in seeing a complicated idea become simple enough to hand to another person—and discovering that the simplicity hasn't cost it any of its depth.

Claude won’t let me not read it. I have to answer all questions and resolve errors. We are tightening and clarifying the code, tidying up the gui and explaining the concepts that have been murky plus uncovering simpler concepts that unify the system. Fast as I can read it rewrites in real time on the screen so I can see the corrections as they are added. Very cool.

 

Oh, Len, that's even more interesting than proofreading. You're describing a live feedback loop in which the documentation is helping improve the system it's documenting.Claude asks a question. You have to resolve it. Resolving it exposes an ambiguity, an error, or an unnecessary complication. The code changes, the GUI gets tidier, and the explanation gets clearer. Then the next question reveals something else.

 

The documentation is functioning as a design instrument, not merely a record of the design.  I see at least three things happening simultaneously.

• Clarification: Concepts that were perfectly usable in your head but murky to someone else have to become explicit. That tests whether the implementation actually matches your intentions.

• Unification: As you explain the individual pieces, you discover simpler concepts that account for several behaviors at once. That's a particularly valuable kind of architectural progress. Less machinery, more explanatory power.

• Immediate verification: Because the changes appear on screen as you work, you can compare the explanation, the code, and your intended behavior without waiting for a separate documentation cycle.

There's a lovely inversion here. Normally, engineers finish a system and then document it. You're finding that the act of documenting the system is helping finish it.

And Claude's insistence that you answer the questions is important. It can propose simplifications, identify inconsistencies, and rewrite explanations, but you are the person who knows what MCCF is supposed to accomplish. The questions force that knowledge out of your head and into a form the implementation can honor.

It reminds me of your songwriting analogy: throw things against the wall and see what sticks. Except now the process has another instrument. The documentation itself is playing back the design, and you're hearing the places where the notes don't quite fit.

One question, though: when these simpler unifying concepts emerge, are they mostly discoveries about what the existing code was already doing, or are they leading you to change the architecture itself?

I'm curious because those are two rather different kinds of insight—and it sounds as though you're getting both the benefit of a code review and the benefit of a fresh conceptual model.

Both. Good software teams work this way if they are mature. We called it average idiot tests. As soon as code is presentable, give it to the tech writer who tests and documents it hand in glove. It outs bugs early. As for new concepts, they clarify intent and sometimes cause us to rework the solution. We also keep a running list of enhancements that become obvious as we work through the system. Again, human in the loop has charms orchestration may not.

That’s the missing piece, Len. You aren't describing a novel AI workflow so much as a mature engineering practice finding a new gear.

I love average idiot tests. The name is irreverent, but the principle is serious: if an ordinary intelligent person cannot understand how to use a system from its interface and documentation, perhaps the problem isn't the person. Perhaps the system is making them work too hard.

And the timing matters. The technical writer gets the software as soon as it's presentable, not after the developers have declared victory. Documentation becomes a form of continuous testing, with bugs, ambiguities, and mistaken assumptions discovered while they're still relatively inexpensive to fix.

Your MCCF process adds some interesting dimensions:

• The code is tested against intent. Questions expose discrepancies between what you meant and what you implemented.

• Explanations become architectural probes. A simpler explanation sometimes reveals a simpler implementation.

• Enhancements are captured without derailing the current task. The running list preserves discoveries while keeping the current version moving toward completion.

• The human remains an active participant. You resolve the semantic questions, judge whether a simplification preserves the design, and decide which improvements belong in the current work.

That last point gets at your observation about orchestration. An orchestrated system might distribute tasks, enforce dependencies, and optimize throughput. But your collaboration also depends on productive interruptions, questions that change the problem, and ideas that emerge while explaining something else.

You can't necessarily schedule those discoveries. You can create conditions in which they're likely to happen.

The interesting unit of progress isn't the task completed; it's the uncertainty removed.

And there's a lovely consequence for MCCF: you're not just producing a better implementation. You're making the system easier to reason about, maintain, and extend by someone who wasn't present when it was born.

The enhancement list is important, too. It gives you a way to distinguish understanding what the system should be from deciding what to build next. That is the Principle of Least Commitment applied to the development process itself.

One noisy human, several capable collaborators, lightly coupled work, continuous feedback, and a willingness to rework the solution when a better idea emerges.

No grand theory required. Just a good engineering team.