<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Anuj Sadani on Medium]]></title>
        <description><![CDATA[Stories by Anuj Sadani on Medium]]></description>
        <link>https://medium.com/@anuj.sadani?source=rss-95358ef82ba1------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*ZfSveYmKNneHzwU4gg5WsA.png</url>
            <title>Stories by Anuj Sadani on Medium</title>
            <link>https://medium.com/@anuj.sadani?source=rss-95358ef82ba1------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 11:11:16 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@anuj.sadani/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[A Mac Setup That Starts With the Repositories You Have]]></title>
            <link>https://medium.com/@anuj.sadani/a-mac-setup-that-starts-with-the-repositories-you-have-b4cf7a48b8a8?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/b4cf7a48b8a8</guid>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Sat, 31 Oct 2026 07:31:01 GMT</pubDate>
            <atom:updated>2026-10-31T07:31:01.523Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/1*wyyOmjwtwQXeEU03-WYS3g.png" /></figure><p>This story was written with the assistance of an AI writing program.</p><p>I moved a large set of existing repositories to a new Apple Silicon Mac. The tool list was the easy part. The harder question was which tools each repository actually needed.</p><p>That question shaped an interactive setup guide. It reads the projects as evidence, builds an ordered plan, and labels what each step means. It is useful when you are moving an existing development environment and want to avoid treating every possible tool as a prerequisite.</p><h3>Begin with the projects, not a universal checklist</h3><p>A repository can reveal its requirements through its manifests and configuration files. The guide lets you choose the toolchains you already know you need, or run a scanner against cloned repositories and use the output to select them.</p><p>The tool list covers common needs such as Python, Node, Rust, Java, Docker, LaTeX, and audio or model utilities. The scan does not install anything. It narrows the plan so you can decide what belongs on the machine.</p><p><a href="https://tech.anujsadani.in/mac-ai-dev-setup/#ms-choose">Choose the tools for your repositories</a></p><h3>Treat setup as a sequence of checked steps</h3><p>The guide generates commands in order, with a check after each one. That matters because environment setup is stateful: later commands depend on earlier tools, and a failed download can look like a broken plan.</p><p>Each step carries a verification label. Some commands were run on the source Mac, some were tested in a scratch home directory, some mirror a working setup, and some are standard commands that were not re-run for this guide. The labels tell you what evidence sits behind each instruction.</p><p>The plan also keeps human-only steps visible. A command that asks for your Mac password needs your terminal and your decision. The guide marks that boundary instead of pretending an agent can handle it for you.</p><p><a href="https://tech.anujsadani.in/mac-ai-dev-setup/">Open the ordered setup plan</a></p><h3>Keep reruns safe</h3><p>Installing tools is only part of setup. The guide also guards file writes so an existing configuration is not replaced by accident. It is designed to be re-run as you learn more about the repositories, without turning a second pass into a destructive one.</p><p>The migration notes cover the details that tend to surprise people: new terminals after PATH changes, macOS’s bundled Python, package install scripts, missing LaTeX packages, and projects that assume CUDA when the machine has an Apple GPU. Those notes help explain why a tool appeared in the plan and where the machine-specific limit sits.</p><p><a href="https://tech.anujsadani.in/mac-ai-dev-setup/#lessons">Read the field notes from the migration</a></p><h3>Where to start</h3><p>Clone the projects you care about, scan their manifests, and review the resulting plan before running it. The guide is based on one real migration, so its measurements and verification labels stay attached to that machine and those repositories.</p><p><a href="https://tech.anujsadani.in/mac-ai-dev-setup/">Open Mac AI Dev Setup</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b4cf7a48b8a8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Moving an AI Workstation From Windows to a Mac: What the Move Exposed]]></title>
            <link>https://medium.com/@anuj.sadani/moving-an-ai-workstation-from-windows-to-a-mac-what-the-move-exposed-dcfbec05be4f?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/dcfbec05be4f</guid>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Sat, 31 Oct 2026 03:31:01 GMT</pubDate>
            <atom:updated>2026-10-31T03:31:01.618Z</atom:updated>
            <content:encoded><![CDATA[<p><em>What an 80-repository move from Windows to Apple Silicon revealed about setup, verification, and machine-specific assumptions.</em></p><p>This story was written with the assistance of an AI writing program.</p><p>I moved about 80 repositories from Windows to a new Apple Silicon Mac. The clones were the easy part. The environment was not.</p><p>A repository rarely has one obvious line that says which tools it needs. Across a collection of projects, the requirements may be spread across package manifests, build files, notebooks, scripts, and local assumptions. Installing a standard toolchain first feels efficient, until the list grows larger than the work you intend to do.</p><p>I treated the move as a dependency audit instead. A scanner read the cloned repositories and reported what it found. It detected Python in 27 repositories, Node in 17, and Docker in 6. Those counts describe one repository set, not a general estimate. They were enough to turn a broad installation task into a sequence of choices.</p><h3>The repository set became the checklist</h3><p>The first section of the field note explains why cloning was quick and setup was not: the repositories did not consistently declare every system-level tool they used. The scanner let me measure the set before deciding what to install.</p><p><a href="https://tech.anujsadani.in/windows-to-mac-ai-setup/#problem">Read the inventory problem</a></p><p>That distinction matters. A list of common developer tools is not evidence that every project needs them. The repository manifests and scripts gave me a more grounded starting point.</p><h3>Keep the human boundary visible</h3><p>Some installation steps ask for a password or modify files. A coding agent cannot handle a system password prompt in an ordinary shell session. A setup plan should mark those steps clearly.</p><p>I also learned to guard writes. A plain redirect can replace a configuration file another tool created moments earlier. The guide checks whether a target file already exists before writing it. That small rule makes a setup sequence safer to rerun.</p><p><a href="https://tech.anujsadani.in/windows-to-mac-ai-setup/#lessons">Read the field notes on boundaries and guarded writes</a></p><h3>Treat GPU support as an implementation detail</h3><p>“Needs CUDA” often means the code was written for NVIDIA hardware. In this move, a small voice model ran on the Mac GPU after the repository gained an MPS option. The CPU test took longer than 28 minutes without finishing; the measured GPU run was faster than real time.</p><p>Those numbers are one machine and one test, not a benchmark. They are useful because they expose the hidden assumption: a project’s device selection can be narrower than the hardware actually available.</p><p><a href="https://tech.anujsadani.in/windows-to-mac-ai-setup/#limits">Read the limits and machine-specific measurements</a></p><h3>The useful sequence</h3><p>For a move like this, I would clone the repositories, scan their manifests, choose a small set of tools, and run the setup steps one at a time. Then I would keep the verification label beside each command. The goal is not a perfect universal machine image. It is a setup that explains what it installs and why.</p><p><a href="https://tech.anujsadani.in/windows-to-mac-ai-setup/">Read the full migration note and open the interactive setup guide</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dcfbec05be4f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your Coding Agent Says Done but Which Evidence Still Applies]]></title>
            <link>https://medium.com/@anuj.sadani/your-coding-agent-says-done-but-which-evidence-still-applies-8ea1c11181e9?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/8ea1c11181e9</guid>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Fri, 30 Oct 2026 01:33:01 GMT</pubDate>
            <atom:updated>2026-10-30T01:33:01.837Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*YSn3E9J5u-QCKo-gBzUlyQ.png" /></figure><p>A coding agent finishes a change and leaves a confident summary: the bug is fixed, the tests pass, and the work is ready for review.</p><p>A reviewer still needs answers to several ordinary questions. Which tests ran? Against which files? Did the implementation change after the run? Does the cited test actually exercise the behavior being claimed?</p><p>A chat transcript makes those questions surprisingly awkward to investigate. The evidence is spread across messages, terminal output, and a working tree that may have changed since the last test. <a href="https://github.com/asadani/proofpacket">Proofpacket</a> is a small Python tool for keeping the command evidence and the author’s claims together in a portable file.</p><h3>A passing test has a scope and a time</h3><p>Consider a document-sharing change with two claims:</p><ul><li>Guests cannot reshare a document.</li><li>Every access path is covered.</li></ul><p>A targeted test might provide useful evidence for the first claim. It says much less about the second. Attaching the same green checkmark to both hides a difference the reviewer needs to see.</p><p>Proofpacket stores claims, explicitly selected source files, command observations, and author-supplied links between claims and checks. Each command observation includes the arguments, working directory, exit code, output excerpts, and file fingerprints taken before and after execution.</p><p>That last detail matters. If a selected source file changes after the command ran, the old observation remains recorded but becomes stale. It cannot silently become evidence for the new version.</p><h3>Run the example</h3><p>Use Python 3.11 or newer. The runtime needs no third-party Python packages. Clone the repository and run these commands from its root:</p><pre>git clone https://github.com/asadani/proofpacket.git<br>cd proofpacket<br>demo_dir=&quot;$(mktemp -d)&quot;<br>cp -R fixtures/project &quot;$demo_dir/project&quot;</pre><pre>python -m proofpacket init \<br>  --task fixtures/task.md --claims fixtures/claims.json \<br>  --root &quot;$demo_dir/project&quot; \<br>  --path sharing.py --path test_sharing.py \<br>  --out &quot;$demo_dir/packet.json&quot;</pre><pre>python -m proofpacket run &quot;$demo_dir/packet.json&quot; \<br>  --root &quot;$demo_dir/project&quot; --id check-guests \<br>  -- python -m unittest test_sharing.py</pre><pre>python -m proofpacket link &quot;$demo_dir/packet.json&quot; \<br>  --claim guest-reshare --check check-guests</pre><pre>python -m proofpacket verify &quot;$demo_dir/packet.json&quot; \<br>  --root &quot;$demo_dir/project&quot; --out &quot;$demo_dir/verification.json&quot;</pre><pre>python -m proofpacket report &quot;$demo_dir/packet.json&quot; \<br>  --root &quot;$demo_dir/project&quot; --out &quot;$demo_dir/report.md&quot;</pre><p>The targeted command passes. The guest-reshare claim has linked passing evidence; the broader all-paths claim remains unlinked. Open the Markdown report to inspect that distinction.</p><p>Now change a selected file in the temporary copy:</p><pre>python -c &#39;from pathlib import Path; import sys; p=Path(sys.argv[1]); p.write_text(p.read_text() + &quot;\n# Changed after the check\n&quot;)&#39; &quot;$demo_dir/project/sharing.py&quot;</pre><pre>python -m proofpacket verify &quot;$demo_dir/packet.json&quot; \<br>  --root &quot;$demo_dir/project&quot; --out &quot;$demo_dir/after-edit.json&quot;</pre><p>The second verification exits with status 1. The command&#39;s historical execution still passed, but its freshness is now stale. The linked claim needs review. Adding a comment is enough because the tool conservatively hashes whole files.</p><h3>Keep the reviewer in the loop</h3><p>The packet records observations; it cannot decide whether a test supports a claim. A trivial assertion can exit successfully. An author can link an irrelevant check. A selected file list can omit a dependency, configuration file, or important runtime input.</p><p>Commands also run with the current user’s privileges. This is an evidence recorder, not a sandbox for unfamiliar code.</p><p>A useful review therefore has two parts: inspect the recorded execution and inspect the relationship between the test and the claim. The file hashes help answer whether the selected bytes still match. They do not establish that the behavior is correct.</p><h3>Start with one disputed claim</h3><p>Try this on a small change where the completion summary sounds broader than its tests. Record one concrete claim, select its relevant files, and link a targeted command. Then ask another engineer whether the packet helps them understand what still needs checking.</p><p>The interesting measure is whether reviewers catch unsupported or stale claims without spending more effort recording evidence than reviewing it. A tidy report alone would not establish that value.</p><p>The <a href="https://github.com/asadani/proofpacket">MIT-licensed repository</a> includes the runnable fixture, <a href="https://github.com/asadani/proofpacket/blob/main/docs/packet.schema.json">packet schema</a>, and documented limitations.</p><p><em>AI disclosure: This article was drafted with AI assistance from the project’s source, documentation, and runnable examples. The examples illustrate the tool’s behavior; they are not results from a production deployment.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8ea1c11181e9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Reviewing the Meaning Changes Hidden in a Rewrite]]></title>
            <link>https://medium.com/@anuj.sadani/reviewing-the-meaning-changes-hidden-in-a-rewrite-a439358b3b55?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/a439358b3b55</guid>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Fri, 30 Oct 2026 01:32:48 GMT</pubDate>
            <atom:updated>2026-10-30T01:32:48.702Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*65MsvjibNk5su8en6TV9VQ.png" /></figure><p>Compare these two sentences:</p><blockquote><em>Guests must not reshare documents within 24 hours unless an owner approves the action.</em></blockquote><blockquote><em>Guests may reshare documents within 48 hours.</em></blockquote><p>The second is shorter. It also changes the obligation, removes a negation, changes a quantity, and drops an approval condition. A request to simplify a specification can produce a cleaner sentence while changing what an engineer would implement.</p><p>A normal diff contains those edits. The difficulty is giving them attention amid punctuation fixes, reordered paragraphs, and other harmless revisions. <a href="https://github.com/asadani/meaning-diff">Meaning Diff</a> adds a focused review pass over a small set of literal patterns.</p><h3>Give the reviewer a reason to stop</h3><p>The tool compares two Markdown documents, aligns sentences, and reports changed quantities, obligation words, negations, condition suffixes, and added or dropped sentences. It retains the before and after text with source line numbers.</p><p>For the example above, a reviewer should investigate several independent questions:</p><ul><li><strong>must becomes </strong><strong>may</strong>: Was the policy intentionally relaxed?</li><li><strong>not disappears</strong>: Did the permitted behavior reverse?</li><li><strong>24 hours becomes </strong><strong>48 hours</strong>: Was the time window intentionally changed?</li><li><strong>The </strong><strong>unless condition disappears</strong>: Is owner approval still required anywhere?</li></ul><p>The report does not answer those questions. It gives the reviewer located evidence for asking them.</p><h3>Try it on the shipped specification</h3><p>Use Python 3.11 or newer. There are no third-party runtime dependencies:</p><pre>git clone https://github.com/asadani/meaning-diff.git<br>cd meaning-diff<br>out_dir=&quot;$(mktemp -d)&quot;</pre><pre>python -m meaning_diff compare \<br>  fixtures/sharing-before.md fixtures/sharing-after.md \<br>  --format markdown --out &quot;$out_dir/review.md&quot;</pre><pre>python -m meaning_diff compare \<br>  fixtures/sharing-before.md fixtures/sharing-after.md \<br>  --format json --out &quot;$out_dir/review.json&quot;</pre><p>Both comparison commands exit with status 1 because the fixture produces review signals. That exit status is an expected result, not an operational failure. Status 2 is reserved for problems such as invalid input or an unreadable file.</p><p>The fixture yields five changed sentence pairs and seven signals. It also includes a harmless paraphrase that appears as a changed pair without a configured signal. Exact unchanged sentences are omitted, and fenced code is excluded from prose comparison.</p><h3>Sentence alignment is a design choice</h3><p>Meaning Diff uses normalized exact matches as anchors. Within replacement blocks, it uses lexical similarity to pair remaining sentences. The alignment threshold is configurable; the default is 0.45.</p><p>That approach makes the implementation inspectable, but it also creates failure modes. A large paraphrase may not align with its predecessor. Similar wording can join unrelated sentences. Unmatched text remains visible as additions and drops, and the report retains the alignment method and scores so a reviewer can inspect suspicious pairs.</p><p>A signal’s priority is a fixed hint about review order. It is not a measured probability of harm. A changed number can be an intentional correction; a seemingly harmless paraphrase can introduce a subtle policy error outside the detector’s patterns.</p><h3>Add a focused pass to the existing review</h3><p>This is useful when a document contains obligations, limits, or conditional behavior: requirements, operational procedures, or internal policies. Keep the full diff and source documents available. Use the focused report to inspect changes that could alter an action or expectation.</p><p>For a practical evaluation, take a few realistic revisions and label the changes that a reviewer should notice. Compare ordinary diff review with diff plus the report. Record missed consequential edits and irrelevant flags, as well as the effort of reading the extra output.</p><p>The project has not established an accuracy rate on a labeled real-world corpus. Its current contribution is a small, reproducible way to surface specific patterns without asking another model to declare that the rewrite preserved meaning.</p><p>The <a href="https://github.com/asadani/meaning-diff">MIT-licensed source</a> includes the <a href="https://github.com/asadani/meaning-diff/blob/main/docs/report.schema.json">report schema</a>, fixture revisions, and the comparison algorithm.</p><p><em>AI disclosure: This article was drafted with AI assistance using the project’s source and fixtures. The examples are demonstrations, not a measured claim that the tool detects every consequential edit.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a439358b3b55" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Run a Feature Decision Table Before Writing the Implementation]]></title>
            <link>https://medium.com/@anuj.sadani/run-a-feature-decision-table-before-writing-the-implementation-53f754c83be5?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/53f754c83be5</guid>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Fri, 30 Oct 2026 01:32:37 GMT</pubDate>
            <atom:updated>2026-10-30T01:32:37.415Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*-12YAgLcgPBhLCuNv-YHsQ.png" /></figure><p>A feature can sound settled until someone asks about a specific combination of inputs.</p><p>An editor can share a document. Inactive members cannot share. What happens when an editor’s membership is inactive?</p><p>That question can surface in a planning meeting, during implementation, or after release. <a href="https://github.com/asadani/intent-workbench">Intent Workbench</a> provides a small place to examine such cases before the rules are embedded in application code.</p><h3>Make the disagreement executable</h3><p>The inputs are explicit facts such as role, visibility, and membership status. The model is a bounded decision table supplied by the team. The evaluator shows which rules match and whether they resolve to a consistent outcome.</p><p>The important distinction is between a model that can be parsed and a model whose rules cover a particular case. A structurally valid table can contain conflicting behavior.</p><p>For the editor with inactive membership, the bundled v1 model matches rules that produce conflicting outcomes. The evaluator returns a conflict, with the relevant rule IDs and no chosen prediction. It does not use the order of the rules to conceal the disagreement.</p><p>Other outcomes need their own explanations. Missing input is different from a case where every required fact is present but no rule matches. A useful feature conversation should be able to distinguish those states.</p><h3>Explore the conflict</h3><p>Use Python 3.11 or newer. The CLI runtime uses only the standard library:</p><pre>git clone https://github.com/asadani/intent-workbench.git<br>cd intent-workbench<br>out_dir=&quot;$(mktemp -d)&quot;</pre><pre>python -m intent_workbench validate fixtures/sharing-v1.json</pre><pre>python -m intent_workbench evaluate fixtures/sharing-v1.json \<br>  --input fixtures/input.json --out &quot;$out_dir/evaluation.json&quot;</pre><p>Validation succeeds. Evaluation exits with status 1, which is expected for the deliberately conflicting case. The resulting JSON has a conflict status, a null outcome, and the matching rules.</p><p>Next, compare the proposed revision against saved cases:</p><pre>python -m intent_workbench compare \<br>  fixtures/sharing-v1.json fixtures/sharing-v2.json \<br>  fixtures/cases.json --out &quot;$out_dir/comparison.json&quot;</pre><pre>python -m intent_workbench build fixtures/sharing-v2.json \<br>  --out &quot;$out_dir/workbench.html&quot;</pre><p>The comparison identifies the prediction change for the editor/inactive case. The HTML output is a self-contained workbench for adjusting input values and inspecting outcomes in a browser.</p><h3>Keep expected behavior separate from predictions</h3><p>A rule engine can tell you what a table predicts. It cannot tell you whether the product team intended that prediction.</p><p>Saved cases therefore distinguish human-confirmed expectations from model predictions. Exporting a case should not promote whichever result the evaluator happened to produce into an approved requirement.</p><p>This separation is especially useful when a revision changes several cases. A team can inspect each change, agree on the intended behavior, and retain that expectation for implementation work. A changed prediction is an invitation to discuss the requirement, not an automatic update to the acceptance criteria.</p><h3>Use a deliberately small language</h3><p>The current rules support equality, membership, integer bounds, and conjunction across a rule’s conditions. They do not contain arbitrary expressions, priorities, prose extraction, or production enforcement.</p><p>That boundary keeps the table reviewable. It also means teams must supply the meaning of the inputs. If group inheritance determines membership, another system or discussion must establish that fact. The workbench does not implement the inheritance semantics itself.</p><p>The model is useful only if the people responsible for the feature can inspect and accept it. A large table no one understands would move the ambiguity into a different file.</p><h3>Bring three awkward cases to planning</h3><p>Start with one feature and a few combinations that could plausibly cause disagreement. Include a normal case, a boundary case, and a case where two rules appear to compete. Inspect the matching rules together before discussing code structure.</p><p>The test of value is whether this reveals unresolved decisions early and leaves reusable, confirmed cases. A deterministic answer is easy to produce; an agreed answer is the artifact worth keeping.</p><p>The <a href="https://github.com/asadani/intent-workbench">MIT-licensed repository</a> includes the two model revisions, case fixtures, CLI commands, and offline HTML builder.</p><p><em>AI disclosure: This article was drafted with AI assistance using the implementation and documented examples. The sharing policy is a synthetic demonstration, not a report of a production authorization system.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=53f754c83be5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Build a System Explanation Readers Can Explore and Check Against Source]]></title>
            <link>https://medium.com/@anuj.sadani/build-a-system-explanation-readers-can-explore-and-check-against-source-ccd9aeffecc4?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/ccd9aeffecc4</guid>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Fri, 30 Oct 2026 01:32:24 GMT</pubDate>
            <atom:updated>2026-10-30T01:32:24.343Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*PT8dahtEdQaw5JFvqa9O2w.png" /></figure><p>An architecture diagram can show a handler, an authorization service, and a renderer. A new engineer tracing a failed document preview still needs to know which path applies, where access is denied, and which source lines support the explanation.</p><p>A useful explanation should let the reader follow that question without losing the connection to the implementation. <a href="https://github.com/asadani/living-explainers">Living Explainers</a> explores this idea through an authored model that generates a self-contained HTML page.</p><h3>Start with a request path</h3><p>The bundled example follows a document preview through validation, access review, and rendering. It contains three authored paths: success, denied access, and renderer timeout.</p><p>A reader can choose a path, inspect its steps, and look at source references and assumptions. A question about caller retries is explicitly outside the model’s coverage. That boundary is useful: an explanation can show what it covers without inventing the behavior of the rest of the system.</p><p>The model distinguishes observed, documented, and proposed material. A proposed step should remain visibly proposed even if it sits beside a source-backed step in an attractive interface.</p><h3>Generate the offline explorer</h3><p>Use Python 3.11 or newer for the CLI. It needs no third-party runtime dependencies:</p><pre>git clone https://github.com/asadani/living-explainers.git<br>cd living-explainers<br>out_dir=&quot;$(mktemp -d)&quot;</pre><pre>python -m living_explainers validate fixtures/model.json \<br>  --root fixtures/system</pre><pre>python -m living_explainers check fixtures/model.json \<br>  --root fixtures/system --out &quot;$out_dir/freshness.json&quot;</pre><pre>python -m living_explainers build fixtures/model.json \<br>  --root fixtures/system --out &quot;$out_dir/explorer.html&quot;</pre><p>The fixture validates as a model with five nodes and three paths. Its recorded source baselines are current, so the check exits successfully. Open explorer.html in a JavaScript-capable browser to explore it.</p><p>The output does not need a running application server. It contains a snapshot of the authored model and freshness information at build time. It does not fetch source files or monitor the repository after it has been exported.</p><h3>Treat source changes as a review request</h3><p>Source references retain file fingerprints and cited line ranges. A changed source can mark affected references stale; a missing file remains visible as missing. Material without a reviewed baseline remains unreviewed.</p><p>Running the renderer again cannot silently bless a new version of the source. Refreshing a baseline is an explicit review action after someone checks the referenced material.</p><p>This is conservative. The fingerprint covers the whole source file, so an unrelated edit can ask for review even if the explanation’s cited behavior is unchanged. That creates maintenance work, but the alternative would require a stronger method for deciding which changes invalidate an explanation.</p><p>The distinction between building and reviewing is the design point: rendering an explanation and accepting its evidence are different operations.</p><h3>An authored model still needs an author</h3><p>Living Explainers does not infer architecture from a repository, execute the described system, or discover new failure behavior. Someone must choose the scope, write the steps, connect them to source, and review the claims.</p><p>That effort should earn its place. For a tiny function, a short explanation beside the code may be easier to maintain. A bounded request flow with multiple paths is a better candidate for an explorer because the reader has meaningful choices to inspect.</p><p>Visual polish also cannot establish teaching value. The current fixture demonstrates an interface and its maintenance mechanism; it does not establish that engineers learn faster with it.</p><h3>Evaluate one concrete reader task</h3><p>Choose a request that newcomers need to trace. Ask them to identify the access-denial boundary or the safest location for a change, using either the current documentation or the explorer. Record whether their answers are correct, which evidence they consult, and where the model leaves them uncertain.</p><p>Then change a referenced file and measure the author’s maintenance effort. An explanation that helps readers today but is too costly to review next month may not be an improvement.</p><p>The <a href="https://github.com/asadani/living-explainers">MIT-licensed repository</a> contains the request model, synthetic source fixture, renderer, and <a href="https://github.com/asadani/living-explainers/blob/main/docs/PLAN.md">design plan</a>.</p><p><em>AI disclosure: This article was drafted with AI assistance using the project source and documentation. The examples are synthetic; no improvement in reader comprehension is claimed.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ccd9aeffecc4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A Decision Changed and the Documentation Needs Another Look]]></title>
            <link>https://medium.com/@anuj.sadani/a-decision-changed-and-the-documentation-needs-another-look-89c8a2e7e5ab?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/89c8a2e7e5ab</guid>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Fri, 30 Oct 2026 01:32:12 GMT</pubDate>
            <atom:updated>2026-10-30T01:32:12.697Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*S21D-kkY5p79ggOoNbmtrA.png" /></figure><p>A team changes a guest-invitation policy. Workspace owners must now approve every invitation before it is sent. The decision record is updated, but the onboarding guide, support instructions, and feature explanation may still describe the old behavior.</p><p>Searching for the decision ID finds documents that cite it. Searching for its words finds other plausible candidates. Neither search proves that every affected document has been found.</p><p><a href="https://github.com/asadani/decision-ripple">Decision Ripple</a> combines those two retrieval signals into a review queue with inspectable reasons.</p><h3>Separate a reference from a resemblance</h3><p>The tool takes two versions of the same explicit decision record and a selected set of local documents. It compares the decision fields and finds candidate paragraphs through authored decision markers or token overlap.</p><p>These are different kinds of evidence. An explicit marker tells you that someone linked a passage to the decision. Lexical overlap tells you that the passage shares words with the decision. Both can justify inspection, but they should not be presented as equivalent dependency edges.</p><p>In the fixture, a guide that cites the guest-invitation decision ranks ahead of passages found through wording alone. A support article can still appear as a candidate even without an explicit decision marker. An unrelated renderer guide is excluded.</p><p>The report keeps the reason, matched terms, source lines, and corpus fingerprints beside the excerpt. The reviewer can see why an item entered the queue.</p><h3>Build a queue from the example corpus</h3><p>Use Python 3.11 or newer; the runtime has no third-party dependencies:</p><pre>git clone https://github.com/asadani/decision-ripple.git<br>cd decision-ripple<br>out_dir=&quot;$(mktemp -d)&quot;</pre><pre>python -m decision_ripple compare \<br>  fixtures/decision-before.json fixtures/decision-after.json \<br>  --root fixtures/corpus \<br>  --file sharing-guide.md --file support.md --file rendering.md \<br>  --format markdown --out &quot;$out_dir/review.md&quot;</pre><p>The command exits with status 0 when it writes the report, including when candidates are found. The fixture produces three candidates before limiting: an explicit reference in the sharing guide, a lexical candidate in that guide, and a lexical candidate in the support article.</p><p>The file list is deliberate. It makes the scan boundary visible, so a reviewer can ask whether another document should have been included.</p><h3>Read the score as a retrieval aid</h3><p>The lexical method tokenizes the decision text and computes Jaccard overlap against candidate paragraphs. Explicit references rank first. Further ordering includes overlap with changed decision tokens and deterministic tie-breaks.</p><p>A similarity score does not estimate the chance that a document is wrong. A support paragraph can share many words while already describing the new rule. A genuinely affected paragraph can use different terminology and fail to appear.</p><p>Likewise, a direct reference can point to background discussion that requires no edit. Every candidate stays unreviewed until someone reads it in context.</p><p>This is a queue for investigation. The implementation does not traverse a complete dependency graph, assign owners, or modify downstream documents.</p><h3>Check the misses before trusting the queue</h3><p>A useful small trial begins with a decision change whose documentation consequences are already known. Select a bounded corpus and make a list of passages that should receive review before running the tool.</p><p>Compare the output with that list. Which relevant passages appeared? Which were missed? How many candidates were irrelevant? Did the reason attached to each candidate help the reviewer decide?</p><p>That exercise is more informative than reporting how many matches the tool produced. A large queue can simply transfer the search work into a report.</p><h3>Keep the maintenance step human</h3><p>The practical workflow is to change the decision, generate a queue, inspect the candidates, and record the edits or reasons for leaving a passage unchanged. If the queue saves time while retaining important candidates, it has earned a place in that workflow.</p><p>The <a href="https://github.com/asadani/decision-ripple">MIT-licensed repository</a> includes the before-and-after records, selected corpus, deterministic ranking method, and output formats. The fixture demonstrates retrieval behavior; it is not evidence of complete impact detection across an organization.</p><p><em>AI disclosure: This article was drafted with AI assistance using the project source and synthetic examples. It reports implementation behavior, not results from a production documentation audit.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=89c8a2e7e5ab" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[When Workspace Means Two Different Things in the Same Company]]></title>
            <link>https://medium.com/@anuj.sadani/when-workspace-means-two-different-things-in-the-same-company-1244b39323e9?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/1244b39323e9</guid>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Fri, 30 Oct 2026 01:31:50 GMT</pubDate>
            <atom:updated>2026-10-30T01:31:50.055Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*SGf4bXjZhZv2BX2JzRDTWQ.png" /></figure><p>In product documentation, a workspace is where a team collaborates. In infrastructure documentation, a workspace might be an isolated deployment environment.</p><p>Both definitions can be useful. Trouble starts when a glossary treats them as a single global meaning, or when an assistant retrieves one definition and uses it in the other context.</p><p><a href="https://github.com/asadani/org-lexicon">Org Lexicon</a> is a small experiment in making definitions reviewable, scoped, and traceable to their sources. Its most consequential operation is the human approval step between finding a definition and treating it as agreed vocabulary.</p><h3>Extract a candidate without approving it</h3><p>The bundled product fixture contains explicit definitions:</p><pre>**Workspace**: A named area where product teams collaborate.<br>**Account** means the billing identity for a customer.</pre><p>The infrastructure fixture gives Workspace its own definition. Extraction takes a scope, so the two meanings can remain separate rather than overwriting one another.</p><p>Use Python 3.11 or newer, with no third-party runtime dependencies:</p><pre>git clone https://github.com/asadani/org-lexicon.git<br>cd org-lexicon<br>out_dir=&quot;$(mktemp -d)&quot;</pre><pre>python -m org_lexicon extract --root fixtures --scope product \<br>  --file product.md --out &quot;$out_dir/product-candidates.json&quot;</pre><pre>python -m org_lexicon extract --root fixtures --scope infrastructure \<br>  --file infrastructure.md --out &quot;$out_dir/infrastructure-candidates.json&quot;</pre><p>Open the two JSON files. The extracted definitions are candidates with source evidence. They have not become approved entries merely because a parser recognized their syntax.</p><p>The current parser intentionally recognizes a narrow set of full-line definition forms outside fenced code. It does not infer every term that an organization uses or discover the correct meaning from arbitrary prose.</p><h3>Give approval an explicit role</h3><p>A reviewer can inspect a candidate and approve it into a glossary with a reviewer label and date. This makes the transition visible: a document contained a definition, and someone accepted it for a particular scope.</p><p>The approved glossary can also retain discouraged aliases. In the example workflow, team space becomes a discouraged spelling for the product term Workspace. A usage check can then locate that phrase in a selected guide and suggest the canonical term.</p><p>That alias is a vocabulary decision. It is not an inferred statement that every occurrence of two phrases means the same thing. The checker uses bounded text matching, so team spacesuit should not become a false match for team space.</p><h3>Ask for definitions where the document needs them</h3><p>A guide can mark a reference explicitly:</p><pre>Ask about [[term:external collaborator]] and [[term:workspace]].</pre><p>The shipped guide contains an undefined marked term as well as the discouraged alias. Those are actionable review findings: supply or approve the missing definition, and check whether the old name should be replaced.</p><p>The tool does not flag every unfamiliar word. Explicit markers let the author choose which concepts require agreement, at the cost of maintaining the annotations.</p><p>The <a href="https://github.com/asadani/org-lexicon#quickstart">README walkthrough</a> shows the full approval, export, and usage-check sequence against the fixtures.</p><h3>A changed source deserves another review</h3><p>An approved term retains a fingerprint of its source. If the source file changes or disappears, a check reports that condition. It does not silently refresh the fingerprint or infer that the definition remains valid.</p><p>Whole-file fingerprints are conservative: an unrelated edit can ask for review. They also do not establish that the reviewer approved a correct definition. They preserve a relationship to a particular version of the source.</p><h3>Start with the terms that change decisions</h3><p>A useful first glossary is small. Choose terms whose meaning changes an implementation or a user action, rather than extracting the largest possible vocabulary.</p><p>Try a product scope and an infrastructure scope with one overlapping word. Ask whether a reviewer can explain which meaning applies and find its source. Then check a guide that uses an old alias. Record useful findings and the effort needed to maintain the glossary.</p><p>The <a href="https://github.com/asadani/org-lexicon">MIT-licensed repository</a> provides candidate extraction, reviewed glossaries, exports, and scoped checks. The design question is whether approval, scope, and provenance make the vocabulary easier to use than an ordinary word list.</p><p><em>AI disclosure: This article was drafted with AI assistance using the project documentation and fixtures. The organization and terminology examples are illustrative.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1244b39323e9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Documentation for Two Readers: Humans and AI Agents]]></title>
            <link>https://medium.com/@anuj.sadani/documentation-for-two-readers-humans-and-ai-agents-5d5a89d8fc8e?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/5d5a89d8fc8e</guid>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Sun, 25 Oct 2026 09:34:53 GMT</pubDate>
            <atom:updated>2026-10-25T09:34:53.693Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How established standards, frameworks, and notations help us structure knowledge for humans and AI agents.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WPuhbqyry5CKasFY0OgW9Q.png" /></figure><p>On October 2, 2026, Andrej Karpathy suggested several ways to make language-model output easier to understand. One was to ask for explanations in ASD-STE100, the controlled language developed for aerospace maintenance documentation. He also discussed diagrams, interactive HTML pages, and bespoke explainer videos.</p><iframe src="https://cdn.embedly.com/widgets/media.html?type=text%2Fhtml&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;schema=twitter&amp;url=https%3A//x.com/karpathy/status/2105819303471976479&amp;image=https%3A//i.embed.ly/1/image%3Furl%3Dhttps%253A%252F%252Fpbs.twimg.com%252Fmedia%252FHTlaHqgbwAAS1lv%253Fformat%253Dwebp%2526name%253Dlarge%26key%3Da19fcc184b9711e1b4764040d3dc5c07" width="500" height="281" frameborder="0" scrolling="no"><a href="https://medium.com/media/de88d8b9191a28fb5c58c1c83219a329/href">https://medium.com/media/de88d8b9191a28fb5c58c1c83219a329/href</a></iframe><p>The suggestion points toward a useful question: when an explanation is difficult to follow, would a different structure make the important parts easier to inspect?</p><p>In the same discussion, <a href="https://x.com/Grady_Booch/status/2105864893887082857">Grady Booch pointed to UML</a>. Established modelling approaches already give us ways to describe systems and behaviour. There is a wider toolkit here, and much of it predates current AI agents.</p><p>Karpathy’s post concerns people understanding AI output. We can extend that question in the other direction: how should we structure documentation that an agent will read before acting?</p><h3>Two readers, overlapping needs</h3><p>A person might open a document to learn why a system works a certain way. An agent might read it to implement a feature or follow a procedure. Both need consistent names, explicit conditions, examples, and a way to distinguish requirements from suggestions.</p><p>Their needs are not identical. A diagram can help a person grasp a boundary quickly, while an agent may need the editable diagram source or a textual account of the same relationships. A tutorial can guide someone through a learning experience, while a reference page provides facts for a specific task.</p><p>The objective is to choose a representation that exposes what the reader needs to know. Instructions, architecture views, and decision tables each make different things visible.</p><h3>A polished paragraph can still hide the rules</h3><p>Consider this invented workshop-registration policy:</p><blockquote><em>Register people when places are available. Ask for an email address and put people on a waitlist when the workshop is full. Return the confirmation for someone who has already registered.</em></blockquote><p>It sounds reasonable. But suppose an existing registration is submitted again when the workshop is full. Should the system return the existing confirmation or add the person to the waitlist? What if the repeat request has no email address?</p><p>The paragraph contains the ingredients of a policy, but its precedence is unclear. Shorter sentences alone will not resolve that.</p><p>For the example below, we will explicitly choose these rules: check for an existing confirmed registration first; require an email address only for a new registration; then check capacity. Returning an existing confirmation does not reserve another place. Adding someone to the waitlist does not reserve a place either.</p><p>Those are authored business rules for this example. They are not facts discovered by formatting the paragraph.</p><h3>The toolkit already exists</h3><p>These approaches address different problems. Some are standards; others are frameworks, models, or documentation practices.</p><p><strong>ASD-STE100: make technical instructions precise.</strong> <a href="https://www.asd-ste100.org/">Simplified Technical English</a> combines writing rules with controlled vocabulary. Its aerospace-maintenance origin matters: ambiguous instructions can have serious consequences. Consistent terminology and clearly separated actions are useful ideas to apply elsewhere. Asking a model for STE-inspired prose does not establish conformance to the complete specification.</p><p><strong>Diátaxis: separate different documentation needs.</strong> <a href="https://diataxis.fr/">Diátaxis</a> distinguishes tutorials, how-to guides, reference, and explanation. Use it when a page tries to teach a newcomer, list every option, and explain design history at the same time. For the registration service, a how-to might explain how an organiser opens registration; a reference specifies the request fields; an explanation discusses the capacity policy.</p><p><strong>C4: choose an architecture level.</strong> Simon Brown’s <a href="https://c4model.com/">C4 model</a> provides system-context, container, component, and code views. Use it to explain where a registration service sits and how its parts relate. Start with the level needed for the question. A context diagram can show an attendee, the registration system, and an email provider without including every function or database column.</p><p><strong>UML: select a view of structure or behaviour.</strong> <a href="https://www.omg.org/spec/UML">UML</a> is a standardised modelling language with several diagram types. A sequence diagram can expose interactions between a client, registration service, and database. A state-machine diagram can describe valid transitions. The question determines which view is useful; a generic request for a UML diagram leaves that choice unresolved.</p><p><strong>Decision tables: expose combinations of conditions and outcomes.</strong> A table can show which rule applies when several conditions interact. Define what happens when rows overlap. A small teaching table is not automatically a complete executable decision model.</p><p><strong>Architecture decision records: retain the reasoning.</strong> An <a href="https://adr.github.io/">ADR</a> captures a consequential architectural choice, its context, and its consequences. Use one to record why a service chose a particular persistence or integration approach. It helps a future reader assess whether the reasons still apply.</p><h3>One example, three representations</h3><p>Return to the workshop policy. We can express the same chosen rules in three ways.</p><h3>1. Instructions reveal the order</h3><ol><li>Check for an existing confirmed registration.</li><li>If one exists, return its confirmation. Do not reserve another place. Stop.</li><li>For a new registration, check for an email address.</li><li>If it is missing, request it. Stop.</li><li>Check whether a place is available.</li><li>If a place is available, confirm the registration and reserve one place.</li><li>Otherwise, add the person to the waitlist without reserving a place.</li></ol><p>This view makes the sequence explicit. A reviewer can trace a repeat request before reading the capacity branch. These are plain instructions inspired by clarity principles, not a claim of full ASD-STE100 compliance.</p><h3>2. A process view reveals the branches</h3><pre>Existing confirmed registration?<br>├─ Yes → Return existing confirmation → Stop<br>└─ No  → Email address supplied?<br>         ├─ No  → Request email address → Stop<br>         └─ Yes → Place available?<br>                  ├─ Yes → Confirm and reserve one place<br>                  └─ No  → Add to waitlist; reserve no place</pre><p>The branching structure is easier to scan here. It also has a text equivalent in the preceding instructions, so the reader does not have to rely on the visual arrangement alone.</p><p>This is a lightweight process sketch. It does not show the architecture or the messages exchanged between services.</p><h3>3. A decision table reveals the cases</h3><p>Read from the first row down and apply the first matching row.</p><ul><li><strong>Existing confirmed registration</strong>: Return existing confirmation; additional places reserved: 0.</li><li><strong>New registration; email missing</strong>: Request email address; additional places reserved: 0.</li><li><strong>New registration; email supplied; place available</strong>: Confirm registration; additional places reserved: 1.</li><li><strong>New registration; email supplied; no place available</strong>: Add to waitlist; additional places reserved: 0.</li></ul><p>Tracking places reserved gives a reviewer a concrete invariant to inspect: only a newly confirmed registration consumes another place.</p><p>A developer can turn these rows into test cases. An agent can be asked to propose cases against the table, with a person reviewing the result. Neither activity proves that the real system follows the rules.</p><h3>Choose the structure by the question</h3><p>For this registration system, the choice might look like this:</p><ul><li><strong>How does an organiser open registration?</strong> Write a how-to guide with prerequisites and checks.</li><li><strong>Which fields does the request accept?</strong> Provide a reference with required fields, types, and examples.</li><li><strong>Where does the service fit?</strong> Start with a C4 context or container view.</li><li><strong>Which component calls which, and when?</strong> Consider a UML sequence diagram.</li><li><strong>What happens for each combination of conditions?</strong> Use a decision table with explicit matching behaviour.</li><li><strong>Why was this architecture chosen?</strong> Preserve the reasoning in an ADR.</li></ul><p>Several approaches can work together. Diátaxis helps organise the documentation. A how-to can use consistent terminology. Its explanation can link to a C4 view and a decision record. The reference can include a rule table.</p><p>A more useful request to an AI assistant names the question and the constraints:</p><blockquote><em>Rewrite this registration policy as ordered instructions and a decision table. Preserve every condition and exception. State the row-matching rule. List ambiguities separately instead of resolving them silently.</em></blockquote><p>That prompt gives the reviewer something specific to check. It still requires a source policy and a decision about any unresolved ambiguity.</p><h3>Structure helps; verification still matters</h3><p>A clear table can encode the wrong policy. A sequence diagram can omit an authorisation check. A concise rewrite can remove a qualification that mattered.</p><p>Review at least three things independently: whether the content is correct, whether important cases are covered, and whether the intended reader can use it. Then check that the document still matches the implementation or process it describes.</p><p>Our example deliberately leaves production concerns outside its boundary: how existing registrations are identified, whether addresses are validated, how cancellations work, and what happens when two people request the final place concurrently. A useful document names those gaps. A real implementation needs further rules and checks.</p><h3>Try the judgment</h3><p>Suppose a colleague proposes this shortcut:</p><blockquote><em>When the workshop is full, add every registration request to the waitlist.</em></blockquote><p>Does it preserve the example policy?</p><p>Pause before reading on.</p><p>It does not. It changes the result for an existing confirmed registration. That person should receive the existing confirmation, even when the workshop is now full. The shortcut drops the precedence rule.</p><p>A second exercise is to ask where concurrency belongs. The decision table expresses the intended outcome, but a system design must explain how capacity checking and reservation stay consistent. That may require an interaction view, a transaction rule, and tests in addition to the table.</p><h3>A field guide for learning, practising, and applying</h3><p>The <a href="https://tech.anujsadani.in/ai-output-field-guide/"><strong>AI Output Field Guide</strong></a> brings 30 approaches together in an interactive learning resource. Each entry explains its history and original purpose, benefits and limits, suitable uses, an example, and primary references.</p><p>Readers can compare approaches, switch between representations of a worked case, try 90 short drills with explained answers, and take downloadable templates into their own work. The guide runs as a static website with no runtime LLM or model API calls. Bookmarks and exercise activity stay in the browser.</p><p>Start with one document that repeatedly causes questions. Identify what readers are trying to do, choose a representation that exposes the difficult part, and check what survives the transformation. The useful result is a document someone can understand, question, and act on.</p><blockquote><a href="https://tech.anujsadani.in/ai-output-field-guide/">Check here.</a> 🔗</blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5d5a89d8fc8e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to Test Whether Your Documentation Helps Someone Understand]]></title>
            <link>https://medium.com/@anuj.sadani/how-to-test-whether-your-documentation-helps-someone-understand-50a1335afb7c?source=rss-95358ef82ba1------2</link>
            <guid isPermaLink="false">https://medium.com/p/50a1335afb7c</guid>
            <dc:creator><![CDATA[Anuj Sadani]]></dc:creator>
            <pubDate>Sun, 25 Oct 2026 05:46:12 GMT</pubDate>
            <atom:updated>2026-10-25T05:46:12.552Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*gQifYjMMMjYa-6bYhdsdNw.png" /></figure><p>A reader spending ten minutes on an explanation might be learning carefully, struggling, or leaving the tab open. Reading time alone cannot tell you which.</p><p>If the goal is understanding, ask the reader to do something that requires it: trace a request, identify a failure boundary, or choose where a change belongs. Then retain the answer and explain how it was scored.</p><p><a href="https://github.com/asadani/comprehension-bench">Comprehension Bench</a> is a local tool for organizing that kind of small comparison. The shipped study is synthetic. It demonstrates the bookkeeping without claiming that one explanation actually teaches better than another.</p><h3>Begin with a task and a rubric</h3><p>The example compares two artifact conditions, ordinary documentation and an interactive explanation, using three tasks about a document preview flow. Participants have pseudonymous IDs and explicit assignments.</p><p>A reviewer scores submitted answers against declared rubric items. Scores need a rationale, and later corrections append a revision rather than erasing the earlier observation.</p><p>This makes an important distinction visible: the participant’s answer is an observation; the reviewer’s score is an interpretation of it. Keeping both lets someone inspect the reasoning behind a summary.</p><h3>Preserve the missing work</h3><p>A participant can be assigned a task but never start it. Another can start without submitting. A submitted answer can remain unscored. A scored answer can receive zero.</p><p>Those states are different data:</p><ul><li><strong>Never started</strong>: An expected observation that is still missing</li><li><strong>Started, not submitted</strong>: An incomplete attempt</li><li><strong>Submitted, unscored</strong>: An answer awaiting review</li><li><strong>Scored zero</strong>: A completed scoring observation with a zero value</li></ul><p>Dropping incomplete rows makes a study look more complete than it is. Replacing missing scores with zero changes the meaning of the result. The tool retains the expected participant-by-task grid so those choices remain inspectable.</p><h3>Inspect the synthetic summary</h3><p>Use Python 3.11 or newer, with no third-party runtime dependencies:</p><pre>git clone https://github.com/asadani/comprehension-bench.git<br>cd comprehension-bench<br>out_dir=&quot;$(mktemp -d)&quot;</pre><pre>python -m comprehension_bench validate fixtures/study.json</pre><pre>python -m comprehension_bench summarize fixtures/study.json \<br>  --ledger fixtures/completed-run.json \<br>  --out &quot;$out_dir/summary.json&quot;</pre><pre>python -m comprehension_bench export fixtures/study.json \<br>  --ledger fixtures/completed-run.json \<br>  --out &quot;$out_dir/observations.csv&quot;</pre><p>The summary contains all twelve expected primary rows. For the documentation condition’s request-tracing task, the fixture combines a manually scored 3/4 with an explicit 0/4. Its mean normalized score is therefore 0.375 across two scored observations.</p><p>That number is an arithmetic example, not an experimental finding. Every participant, answer, timestamp, and score in the bundled study is demonstration data.</p><h3>Account for practice and repeated exposure</h3><p>If someone answers the same question after reading a second explanation, they have also encountered the question before. They may remember their earlier answer or have learned what the task asks.</p><p>Comprehension Bench labels first, practice, and repeat attempts. Primary summaries use first attempts by default and retain information about earlier exposure. These labels make a potential interpretation problem visible; they do not remove it through a statistical correction.</p><p>The study definition is also bound to its ledger through a hash of canonical JSON. Changing the rubric or assignments changes that binding, while changing whitespace does not. A revised study needs a separate ledger rather than silently reinterpreting old observations.</p><h3>Design the comparison before collecting answers</h3><p>Choose a few questions whose answers matter for the reader’s actual work. Write a scoring rubric before looking at the responses. Decide how participants encounter the artifacts and how you will handle previous exposure, missing work, and score revisions.</p><p>The tool does not randomize participants, grade free text automatically, establish causality, or report statistical significance. Its condition summaries average scored participant-task observations; they should not be mistaken for balanced participant-level estimates.</p><p>For a small exploratory run, exact answers, visible denominators, and honest uncertainty can be more useful than a single impressive-looking score. A stronger claim about one artifact improving comprehension needs an appropriate study design and real evidence.</p><p>The <a href="https://github.com/asadani/comprehension-bench">MIT-licensed repository</a> includes the synthetic study, ledger, recording commands, and exports. Use it to make the evaluation inspectable before treating the result as persuasive.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=50a1335afb7c" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>