/skill-creator and /code-simplifier plugins. I need to check out the official brainstorming skill next.llms.txt to search the docs, and then fetch the MD raw files. Don’t just use our sensible-docs MCP server for docs search!” Then again, I could be wrong, and LLM token use will get so efficient and so cheap that it won’t be a concern..claude dir is full of docs-writing skills, preferences, style guides, and templates. And the crazy thing is, they really do seem to work well! I’m growing and changing the infrastructure fast – this snapshot will probably be out of date in half a week:.claude/
├── preferences/
│ └── editorial-preferences.md
└── skills/
├── create-concept-doc/
├── create-docs-example/
├── create-new-doc/
├── revise-doc-style/
├── sensible-changelog/
├── sensible-integration-guide-gen.../
├── sensible-style-guide-generator.../
├── update-docs-from-pr/
├── update-existing-doc/
└── upload-pr-extractor/
style-guide/
├── changelog-style-guide.md
├── concept-topic-template.md
├── config-library-supported-docu.../
└── integration-guide-template.md
Next up: check out a skill-validator whose author claims the output of Claude’s skill-creator often actually fails her validation tool!
I’d say I’m mostly on the tactical side of DX. If somebody’s providing the overall strategy—like “let’s target junior developers for this on-boarding experience”—I’m the person implementing that vision. And since I think in terms of information architecture and detailed systems of information, I’ve come to believe that developer experience lives in the details.
I’m not the person who’s going to completely overhaul a domain model for how we think about an SDK. But I am the person who’s going to think through the implications of a new domain model, and make sure it’s self-consistent. I’m where the rubber hits the road-—like, is this actually working or not working?
Domain overhauls don’t come around every day, though, so I think my biggest day-to-day tactic for DX is the “docs-first” approach. Is that a techcomm industry term? I feel like it must be. Anyway, when a new feature is under discussion, I mock up documentation to see how easy it is to describe. If it’s awkward – like the naming or interface requires a lot of explanation – then I mock up docs for an alternative interface or naming structure or parameterization of the feature, till I hit on something elegant. Then I propose it.
The other thing about docs-first is that it gives me lead time for stopping developers from creating product sprawl or exposing “inside baseball” features to the public before they’ve gotten into production. Getting rid of a public feature is a much harder ask than not exposing it in the first place.
I’ll walk through some examples from my work with Sensible (a document AI platform) to show what this looks like in practice.
When my client Sensible was in the early days of LLM features, they used an embeddings approach for scoring relevant document chunks to find prompt context. They soon evolved to finding prompt context through per-page document summarization. Then they leveled up again to offer summarization based on logical splits in the document (like section headings) rather than on page boundaries.
The research engineer who was implementing this outline-based summarization created a document_outline preprocessor that would chunk a document semantically into logical segments. This outline would then influence how a downstream LLM method (query_group) searched the document.
I helped the engineer name the preprocessor, but as soon as I mocked up docs showing the interaction between this preprocessor and a downstream query_group LLM method, I realized there was a domain model inconsistency. The query_group method already had a search_by_summarization boolean parameter that controlled how the LLM searched the document. This new preprocessor would create a weird side effect—it would change how query_group searched, but that configuration lived in a totally different object.
We had a meeting to discuss my findings, in which I proposed turning search_by_summarization from a boolean into an object with explicit options and backward compatibility. With other engineers’ input, we arrived at a new solution:
// OLD: Implicit side effect
{
"preprocessors": [
{ "type": "document_outline" } // Magically changes search behavior
],
"fields": [
{
"method": {
"id": "query_group",
"search_by_summarization": true // Boolean. side-effect: This boolean would be implicitly ignored if the document_outline preprocessor is configured!
}
}
]
}
// My proposal: Explicit configuration
{
"fields": [
{
"method": {
"id": "query_group",
"search_by_summarization": "outline" // or "page". for backward compatibility, "true" defaults to "page"
}
}
}
]
}
Thankfully, we avoided creating a preprocessor that would have had these invisible side effects on an extraction method when really we should have been configuring the extraction method directly.
Sensible automates document data processing, and offers dozens of preprocessors for cleaning up messy documents prior to data extraction, like for OCR, ligatures, or line splitting and merging. A software engineer wanted to create a new remove_pages preprocessor so users could ignore irrelevant pages. But I quickly pointed out that we already had two preprocessors for manipulating page ranges, as well as existing match parameters on several preprocessors for selecting pages. So I proposed parameterizing the existing filter_pages preprocessor using a match or match_all parameter for removing pages. That way we’d avoid multiplication of similar preprocessors (and all the docs explaining their differing nuances in usage) and stay consistent with existing patterns. The product manager accepted my proposal. By catching this during the documentation phase, we prevented a redundant feature that would have needed ongoing maintenance and created user confusion about which preprocessor to use.
When I took on my client Optimizely in March 2020, they were pivoting to a developer audience and planning a major SDK overhaul. They had introduced the notion of feature flags on top of their existing A/B testing features, but the relationship between them was unclear. Were they separate things? Was one a subset of the other?
I’d say my primary contribution to the domain overhaul was getting involved in design conversations early on. I noticed that the API team and UI team weren’t quite aligned on how they were presenting the relationship between the two concepts. Both teams were working toward making flags the root concept, with experiments as a type of flag rule, but their terminology was inconsistent. I could raise points like “we need more correspondence between the sendEvent parameter and the decisionLogged field” or “why are we prominently exposing experimentKey in the API when the new UI will be focused almost exclusively on the flagKey?” By mocking up documentation for this new model and writing actual code examples, I could spot where the API and UI were diverging in ways that would confuse developers.
The effort for me was worth it, because when I went to conduct an information architecture overhaul of their existing feature flag doc set, I could keep the docs structure clean and consistent, and all the little inconsistencies I would have had to otherwise document and explain were already polished away. For an example of a technical guide I created (since edited by other authors) explaining feature flags, see Create feature flags. I like to think that the DX that went into those docs is invisible, unless you’d seen the hypothetical messier experience!
]]>]]>
“…Their documentation is best in class and from what I can tell, our engineers enjoyed integrating [the API]…” - public G2 review
“We routinely receive compliments on your docs from other founders, prospective engineering hires, regulatory pen-testers, and implementation partners.” - CEO of client
“Your docs are in the #3 top sources of high-quality first prospect meetings for us” - sales team of client
“On the strength of your docs when we were an early-stage startup, many of our prospects thought we were well established and had been around for years” - CEO of client
“the way your documentation was structured-—it was built for developers. Usually when you see a company that gets that, that’s usually a good smell.” - case study pull quote
It was my first time using Claude Code, and witnessing an LLM edit local files on my laptop was mind-blowing. I’m now fired up about other docs-automation coding projects, and I’ve already made my first few commits on a project I’ll probably blog about soon!
To return to llms.txt – I’d heard that Claude Code could easily go off the rails without proper guidance, and I see it’s true! Even with such a simple task, I had to continually prevent it from barking up the wrong tree. The descriptions it generated in llms.txt needed some light hand editing, too.
I also then used the llms.txt to implement another best practice (adding descriptions to the frontmatter of our MD topics, a long-neglected task). I’ll figure out how to automate updating llms.txt and keep the descriptions in sync using Claude Code and GitHub actions later.
]]>Which lines in this topic contain MDX syntax errors? Provide reasoning, evidence, and line numbers. Asking for “reasoning” and “evidence” seemed to greatly improve the results. Of course, it wasn’t perfect – as a sanity test, I asked the LLM if an MD topic contained any curly braces that weren’t properly contained in code fences. The LLM replied no – even though I was staring at the offending curly brace in question!main branch in GitHub to a semantic version?
main branch, and instead treat a versioned branch as your permanently open, published branch, e.g., v1.0. That seems to be working for me at present, but what that meant is that I was constantly ignoring prompts from GitHub to create pull requests from my versioned branch into main, until I changed my default branch in my repo settings. My main branch is simply empty at this point; renaming it or adding content to it seems to immediately break the sync.<br/> tags in tables, for example – hugely important for some of my reference topic formatting, and not a given for MD to MDX conversions.Footnotes
The biggest was that the mandatory upgrade broke my existing third-party GitHub integration, which relied on an older version of the Readme API. I chose it at a time when Readme’s own GitHub integration was much less powerful than it now is. I will move heaven and earth to achieve static site generation rather than submit to the inefficiencies inherent in authoring docs in a webapp! Even if it meant choosing a third-party open source tool that’s now archived, it was still worth it.
You can’t use bidirectional sync and the CLI together; they’re separate tools requiring different static file directory structures. The structure required by the bidirectional sync appears more elegant and maintainable to me.
It does appear that through the web app, someone can make minor edits to the MDX in a special section of each reference page that doesn’t show up in the spec source. Readme combines those MDX edits plus your spec file to publish the API reference. I’m guessing this afforance is for contributors who want to add general info through the Readme web UI, but don’t want to get into the weeds of API reference editing. I’ll probably migrate any such contributions out of the MDX and into my spec just to keep things centralized.
To that end, recently I researched competitors’ blog content for Sensible. I searched on a particular blog post theme title (I googled “Highs and lows of extracting data from bank statements”, if you’re interested). I was surprised by how many of the top search results were obviously (to my eye) AI generated, and how similar they all were. Aside from being uniformly generic and high level, they sometimes contained the same headings and bullet points with minor variations. They were even the same at the level of specific phrases. “In today’s data-driven world…” showed up in the introductions more times than I could count. It strongly reminded me of the conman who sells the same “spirit fingers” choreography to competing cheerleaders in the 2000 movie Bring It On. Everyone’s been sold the same song and dance!
Anyway, I’m currently preparing to write a new series of AI-assisted blog posts for this client, and as always, I think the way to actually provide value to the reader is to ground the post in data only my client has access to. In my last series, the posts were grounded in the handwritten code samples and the comments the AI generated for those samples. This time around, the series will be grounded in transcribed interviews I conduct with our CSE team, so we can tell real (anonymized) implementation stories, with all their highs and lows.
]]>I found a pattern consistent with my other experiments: AI-generated changelogs are fine for higher-level, less technical announcements, and fairly unsatisfactory for more technical or detailed announcements.
Here are a few examples.
I wanted to announce a new feature for my client Sensible. End users can now use “named anchors” to define, then reference a text match, for more concise syntax.
Here’s Claude’s attempt, and my beef with it:
New feature: Named anchors for reusable anchor definitions
You can now define named anchors and reuse them across multiple fields using the new
anchorDefinitiontype. This eliminates redundant anchor configuration and enables cleaner syntax when multiple fields share the same anchor logic. Define a named anchor with"type": "anchorDefinition"and anameparameter, then reference it in other fields using"anchor": {"ref": "anchor_name"}. Named anchors work within Conditional methods, allowing you to define language-specific or context-dependent anchors that can be referenced by subsequent fields.For more information, see Reuse anchor variables.
Commentary: This assumes the reader knows an anchor’s purpose, which isn’t a given. It’s also overly verbose given that most technical readers are familiar with variable declaration and reference as fundamental to coding languages. A code example would be much simpler. It also misses out on an advanced use case.
Here’s my stab at it. For the sake of the experiment, I wrote this before prompting Claude so I wouldn’t bias my own writing:
You can now name and reuse anchors as variables for concise syntax. Anchors are labels that locate data for layout-based methods.
Example syntax:
"fields": [ { /* declare a complex named anchor variable for later reuse */ "type": "anchorDefinition", "name": "liability_workers_comp", "anchor": { "start":{"text":"Certificate of liability insurance","type":"equals"}, "match":{"text":"workers compensation","type":"equals"}, "end":{"type":"equals","text":"the acord name and logo are registered marks of acord"} } }, { /* extract text from a box 1.15" to the right of the named anchor */ "id": "subrogation_waived", "method": { "id": "box", "offsetX": 1.15, "position": "right" }, "anchor": { "ref": "liability_workers_comp" } },You can conditionally assign values to anchor variables depending on previously extracted document data. For example, assign a
"customer_id"anchor the value of either"customer number"or"identificación del cliente"depending on the form’s language. For more information, see Anchor variables.
I was also unsatisfied with Claude’s attempt to write a deprecation announcement. I wanted to communicate a change to my client’s code editor.
Here’s Claude’s attempt:
Deprecation: Sensible Instruct visual authoring interface removed
The Sensible Instruct visual authoring interface has been removed. Configuration authoring is now exclusively done in JSON using SenseML syntax.
The updated interface provides a streamlined experience with compact visual output representation and JSON output in the right pane. You can toggle between these views while working entirely in the JSON-based SenseML editor.
Previously supported Sensible Instruct methods (Query, List, and Table) remain available as SenseML methods with JSON configuration.
Commentary: Again, lots of telling without showing. Too much passive voice. Without some tailor-made prompting, Claude also can’t glean from the docs that we’re removing this feature in order to pave the way for a better feature.
Here’s my version, again written without glancing at Claude:
]]>Deprecation: Sensible Instruct visual authoring tool
We’ve removed Sensible Instruct, a visual tool for authoring LLM-based SenseML methods that augmented JSON-based authoring. Stay tuned for new ways to author LLM-based methods in future.
By default, you now author all SenseML methods in JSON and view extracted document data in a compact visual format. You can also switch between viewing output visually or as JSON.
Compact visual view of output: [screenshot]
JSON view of output: [screenshot]
Here’s a recent example of a blog post published using this setup:
How to extract data from CMS 1500 forms with Sensible
And for comparison’s sake, here’s an example of a similar blog post I wrote without AI assistance:
How to extract from rent rolls with LLMs and Sensible
I should note that even with a fairly successful prompt like this one, there’s still a substantial editorial process. For example, for this blog post, I made the following manual edits:
Even with this editorial process, Claude still roughly halved the time I’d normally spend on a post like this. I expect it to save me even more time in the future, since I spent a lot of that time on reusable Claude project configuration.
]]>TLDR: The AI performed poorly. It hallucinated heavily about the niche language, to the extent that its code examples were worse than useless. This is in contrast to the success I’ve had with basic code examples in well-known languages like Python.
My methodology was as follows:
I authored the reference docs for the custom operator myself, using the unit tests and comments in the operator’s pull request.
I asked Claude to author the reference docs. As a baseline, I gave it the code declaring the operator’s functionality. Beyond that, I provided varying levels of context:
Prompt #3 was the most successful, but none of these prompts returned satisfactory results. For comparison, here’s my docs, versus the results of the most successful prompt.
Let
Use this operator to declare named variables scoped to the Let operator. This operator addresses JsonLogic’s lack of built-in support for named variable declaration.
{ "let": [ { /* 1st arg: initialize named variables using key/value pair syntax */ }, { /* 2nd arg: operate on the named variables. Sensible evaluates variables in order */ } ] }Example
{ "fields": [], "postprocessor": { "type": "jsonLogic", "rule": { "let": [ { /* declare values with key:value pair syntax */ "a": 5, "b": 3, /* c is sum of a + b (8) */ "c": { "+": [ { "var": "a" }, { "var": "b" } ] } }, /* operate on named values (5 * 8) */ { "*": [ { "var": "a" }, { "var": "c" } ] } ] } } }This returns:
/* postprocessor output */ 40
Here’s the prompt:
write a reference documentation page for this custom JsonLogic operation,
in the same style as the documentation pages in your project knowledge base:
function op_let(
// content redacted; private code base
logicEngine.addMethod(
"let",
{ traverse: false, method: op_let },
{ useContext: true }
);
The results:
do operation that’s not supported in JsonLogic.Here are the results:
]]>Let operation
Use the let operation to define temporary variables within the scope of a JsonLogic expression. This provides a way to create named intermediate values that can be referenced in subsequent expressions, making complex transformations more readable and maintainable.
Parameters
Parameter | Description
— | —
1 | An object with variable names as keys and JsonLogic expressions as values
2 | The JsonLogic expression to evaluate using the defined variables{ "let": [ { "variable1": JsonLogic expression for value1, "variable2": JsonLogic expression for value2, ... }, JsonLogic expression using defined variables ] }Examples
Config
{ "id": "calculated_invoice", "method": { "id": "customComputation", "jsonLogic": { "let": [ { "subtotal": { "var": "invoice_subtotal.value" }, "tax_rate": { "var": "tax_rate.value" }, "tax_amount": { "*": [ { "var": "subtotal" }, { "/": [ { "var": "tax_rate" }, 100 ] } ] } }, { "eachKey": { "invoice_summary": { "eachKey": { "subtotal": { "var": "subtotal" }, "calculated_tax": { "var": "tax_amount" }, "total": { "+": [ { "var": "subtotal" }, { "var": "tax_amount" } ] }, "tax_rate_percentage": { "cat": [ { "var": "tax_rate" }, "%" ] } } } } } ] } } }Example document
The following image shows the example document used with this example config:
Show ImageOutput
{ "calculated_invoice": { "invoice_summary": { "subtotal": 850.00, "calculated_tax": 68.00, "total": 918.00, "tax_rate_percentage": "8%" }, "type": "object" } }Notes
- Variables defined in the let operation are accessible only within the scope of the second parameter.
- Variable definitions can reference previously defined variables within the same let operation. For example, if you define variables x and y, the definition of y can reference x.
- Variables are evaluated in the order they appear in the definition object.
- The operation maintains access to the document context, so you can still use the var operator to access document data.
- Variable names in the let operation can be any valid JSON property name.
- If a variable name conflicts with a field in the document context, the variable definition takes precedence within the scope of the let operation.
Use cases
This operation is particularly useful for:
- Breaking down complex calculations into named steps for better readability
- Avoiding repeating the same calculation multiple times
- Creating intermediate values that can be referenced multiple times in a complex transformation
- Building complex objects with multiple derived fields
- Organizing multi-step data transformations in a clear, logical manner
For other JsonLogic operations in Sensible, see JsonLogic extensions.